1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
= Asciidoctor Inter-doc Reference Text
// 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
ifndef::npm-readme[]
=== Ruby
Install {gem-name} from Rubygems:
[source, sh, subs="+attributes"]
gem install {gem-name}
or to install the latest development version:
[source, sh, subs="+attributes"]
gem install {gem-name} --pre
=== Node.js
endif::npm-readme[]
Install {gem-name} from npmjs.com:
[source, sh, subs="+attributes"]
npm install --save {gem-name}
== Usage
ifndef::npm-readme[]
=== CLI
If you invoke Asciidoctor from command-line, use option `-r` to load the extension:
[source, sh, 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
endif::npm-readme[]
[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.
|