Asciidoctor Inter-doc Reference Text

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

Ruby

Install asciidoctor-interdoc-reftext from Rubygems:

gem install asciidoctor-interdoc-reftext

or to install the latest development version:

gem install asciidoctor-interdoc-reftext --pre

Node.js

Install asciidoctor-interdoc-reftext from npmjs.com:

npm install --save asciidoctor-interdoc-reftext

Usage

CLI

If you invoke Asciidoctor from command-line, use option -r to load the extension:

asciidoctor -r asciidoctor-interdoc-reftext README.adoc

Ruby

Just require 'asciidoctor-interdoc-reftext'. However, if you don’t want the extension to be automatically registered in Asciidoctor, require 'asciidoctor/interdoc_reftext/processor' instead.

Important

Bundler automatically requires all the specified gems. To prevent it, use gem 'asciidoctor-interdoc-reftext', require: false.

Node.js

// 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,
})

Options:

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.