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#[]

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

<a href="other.html">other.html</a>

but this extensions converts it into:

<a href="other.html">Other Document</a>

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

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

xref:other#sec1[]

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

<a href="other.html#sec1">The First Section</a>

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.js')()
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.