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.

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.