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:
but this extensions converts it into:
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:
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-reftextor to install the latest development version:
gem install asciidoctor-interdoc-reftext --preNode.js
Install asciidoctor-interdoc-reftext from npmjs.com:
npm install --save asciidoctor-interdoc-reftextUsage
CLI
If you invoke Asciidoctor from command-line, use option -r to load the extension:
asciidoctor -r asciidoctor-interdoc-reftext README.adocRuby
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, usegem '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,
})- asciidocExts
-
AsciiDoc file extensions (e.g.
.adoc). Default is['.adoc', '.asciidoc', '.ad']. - raiseExceptions
-
Whether to raise exceptions (
true), or just log them (false). Default istrue.
License
This project is licensed under MIT License. For the full text of the license, see the LICENSE file.