asciidoctor-interdoc-reftext

= Asciidoctor Inter-doc Reference Text :source-language: shell // custom :gem-name: asciidoctor-interdoc-reftext :gh-name: jirutka/{gem-name} :gh-branch: master :codacy-id: 7f60adeeb3fc49ee85863df2c65cd4eb

ifdef::env-github[] image:https://travis-ci.org/{gh-name}.svg?branch={gh-branch}[Build Status, link="https://travis-ci.org/{gh-name}"] image:https://api.codacy.com/project/badge/Coverage/{codacy-id}["Test Coverage", link="https://www.codacy.com/app/{gh-name}"] image:https://api.codacy.com/project/badge/Grade/{codacy-id}["Codacy Code quality", link="https://www.codacy.com/app/{gh-name}"] image:https://img.shields.io/gem/v/{gem-name}.svg?style=flat[Gem Version, link="https://rubygems.org/gems/{gem-name}"] image:https://img.shields.io/npm/v/{gem-name}.svg?style=flat[npm Version, link="https://www.npmjs.org/package/{gem-name}"] image:https://img.shields.io/badge/yard-docs-blue.svg[Yard Docs, link="http://www.rubydoc.info/github/{gh-name}/{gh-branch}"] endif::env-github[]

This project is an http://asciidoctor.org/[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:

// GitHub doesn't render Example block as a box. [subs="+macros"]

link:other.html[other.html]

but this extensions converts it into:

[subs="+macros"]

link:other.html[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:

[subs="+macros"]

link:other.html#sec1[The First Section]

where “The First Section” is title of the section with id sec1 in other.adoc.

== Installation

=== Ruby

Install {gem-name} from Rubygems:

[source, subs="+attributes"] gem install {gem-name}

or to install the latest development version:

[source, subs="+attributes"] gem install {gem-name} --pre

=== Node.js

Install {gem-name} from npmjs.com:

[source, sh, subs="+attributes"] npm install --save {gem-name}

== Usage

=== CLI

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

[source, subs="+attributes"] asciidoctor -r {gem-name} README.adoc

=== Ruby

Just require '{gem-name}'. 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 '{gem-name}', require: false.

=== Node.js

[source, js, subs="+attributes"]

// Load asciidoctor.js and {gem-name}. const asciidoctor = require('@asciidoctor/core')() const interdocReftextExt = require('{gem-name}')

// 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:

[source, js]

// ...

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 http://opensource.org/licenses/MIT/[MIT License]. For the full text of the license, see the link:LICENSE[LICENSE] file.