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

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