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
|
= 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/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
To install (or update to the latest version):
[source, subs="+attributes"]
gem install {gem-name}
or to install the latest development version:
[source, subs="+attributes"]
gem install {gem-name} --pre
== Usage
Just `require '{gem-name}'`.
If you invoke Asciidoctor from command-line, use option `-r` to load the extension:
[source, subs="+attributes"]
asciidoctor -r {gem-name} README.adoc
If you don’t want the extension to be automatically registered in Asciidoctor, don’t _require_ `{gem-name}`, but `asciidoctor/interdoc_reftext/processor`.
IMPORTANT: Bundler automatically _requires_ all the specified gems.
To prevent it, use +
`gem '{gem-name}', require: false`.
== 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.
|