59. Bibliography

AsciiDoc has basic support for bibliographies. AsciiDoc doesn’t concern itself with the structure of the bibliography entry itself, which is entirely freeform. What it does is provide a way to make references to the entries from the same document and output the bibliography with proper semantics for processing by other toolchains (such as DocBook).

In order to reference a bibliography entry, you need to assign a non-numeric label to the entry. To assign this label, prefix the entry with the label enclosed in a pair of triple square brackets (e.g., [[[label]]]). We call this a bibliography anchor. Using this label, you can then reference the entry from anywhere above the bibliography in the same document using the normal cross reference syntax (e.g., <<label>>).

By default, the bibliography anchor and reference to the bibliography entry is converted to [<label>], where <label> is the ID of the entry. If you specify xreftext on the bibliography anchor (e.g., [[[label,xreftext]]]), the bibliography anchor and reference to the bibliography entry converts to [<xreftext>] instead.

If you want the bibliography anchor and reference to appear as a number, assign the number of the entry using the xreftext. For example, [[[label,1]]] will be converted to [1].

The bibliography entries themselves are declared as items in an unordered list. You promote a normal unordered list to a bibliography list by adding the bibliography style. However, to be conforming, bibliography lists must be contained inside a bibliography section. A bibliography section is a section with the special bibliography style. By adding the bibliography style to the section, you implicitly add it to each unordered list in that section.

If the bibliography style is used on an unordered list outside of a bibliography section, the resulting behavior is undefined.

Let’s consider an example.

Bibliography with inbound references
_The Pragmatic Programmer_ <<pp>> should be required reading for all developers.
To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>.

[bibliography]
== References

- [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer:
  From Journeyman to Master. Addison-Wesley. 1999.
- [[[gof,2]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns:
  Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

This renders as:

The Pragmatic Programmer [pp] should be required reading for all developers. To learn all about design patterns, refer to the book by the “Gang of Four” [2].

References

  • [pp] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999.

  • [2] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

If you want more advanced features such as automatic numbering and custom citation styles, try the asciidoctor-bibtex project.

To escape a bibliography anchor anywhere in the text, use the syntax [[[word]]]. This prevents the anchor from being matched as a bibliography anchor or a normal anchor.