No commit activity in last 3 years
No release in over 3 years
Asciidoctor extension providing implicit (automatic) reference text (label) for inter-document cross references
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.11
~> 1.16
~> 13.0
~> 3.7
~> 0.51.0
~> 0.17.1
~> 0.9

Runtime

>= 1.5.6, < 3.0
 Project Readme

Asciidoctor Inter-doc Reference Text

Build Status Test Coverage Codacy Code quality Gem Version npm Version Yard Docs

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-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.