Asciidoctor-interdoc-reftext NPM

This project is an Asciidoctor extension providing implicit (automatic) reference text (label) for inter-document cross references.

Examples

When you define a cross reference to another document “other.adoc” without a label, e.g.:

xref:other.adoc#[]

Asciidoctor converts it into a plain link with the target document’s path as a text:

other.html

but this extensions converts it into:

Other Document

where “Other Document” is a title of the other.adoc.

Similarly with cross reference to a section in another document, e.g.:

xref:other.adoc#sec1[]

Asciidoctor converts it in the same way as above, but this extensions converts it into:

The First Section

where “The First Section” is title of the section with id sec1 in other.adoc.

Installation

Install asciidoctor-interdoc-reftext from npmjs.com:

npm install --save asciidoctor-interdoc-reftext

Usage

// Load asciidoctor.js and asciidoctor-interdoc-reftext.
const asciidoctor = require('@asciidoctor/core')()
const interdocReftextExt = require('asciidoctor-interdoc-reftext')

// See documentation at the end of this section.
const options = {
  asciidocExts: ['.adoc'],
}

// Configure the extension and register it into the global registry.
interdocReftextExt.register(asciidoctor.Extensions, options)

// Convert the file to HTML.
asciidoctor.convertFile('./README.adoc')

If you don’t want to register the extension globally, you can also pass a custom registry to the register function:

// ...

const registry = asciidoctor.Extensions.create()
interdocReftextExt.register(registry, options)

const html = asciidoctor.convertFile('./README.adoc', {
  'extension_registry': registry,
})

asciidocExts
AsciiDoc file extensions (e.g. .adoc). Default is ['.adoc', '.asciidoc', '.ad'].

raiseExceptions
Whether to raise exceptions (true), or just log them (false). Default is true.