Preprocessor Extension Example

Purpose: Detect a // draft: comment anywhere in the document, set the status attribute to DRAFT, and inject a visible warning banner at the top of the document before parsing begins.

sample-release-notes.adoc

= Release Notes

== New Features

// draft: section incomplete, need to add more details

In this release, we introduced the following features.

DraftPreprocessor

draft-preprocessor.js

export default function (registry) {
  registry.preprocessor(function () {
    this.process(function (doc, reader) {
      const isDraft = reader.lines.some(l => /^\/\/\s*draft:/i.test(l))
      if (isDraft) {
        doc.setAttribute('status', 'DRAFT')
        reader.lines.unshift('WARNING: This document is a draft and may change without notice.', '')
      }
      return reader
    })
  })
}

Usage

import { Extensions, loadFile } from '@asciidoctor/core'
import registerDraftPreprocessor from './draft-preprocessor.js'

const registry = Extensions.create()
registerDraftPreprocessor(registry)

const doc = await loadFile('sample-release-notes.adoc', { extension_registry: registry })
console.log(doc.getAttribute('status')) // 'DRAFT'
const html = await doc.convert()
// The rendered document starts with a WARNING admonition block