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).

Bibliography section syntax

To conform to output formats, a bibliography must be its own section at any level. The section must be assigned the bibliography section style. By adding the bibliography style to the section, you implicitly add it to each unordered list in that section.

You would define the bibliography as a level 1 section (==) when:

  • the doctype is article

  • the doctype is book and the book doesn’t contain any parts

  • the bibliography is for a part

[bibliography]
== Bibliography

You can also define it as a deeper section, in which case the doctype doesn’t matter and it’s scoped to the parent section.

If the book has parts, and the bibliography is for the whole book, the section is defined as a level 0 section (=).

[bibliography]
= Bibliography

Bibliography entries syntax

Bibliography entries are declared as items in an unordered list.

Example 1. Bibliography with 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,gang]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides.
Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

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>>).

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” [gang].

References

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

  • [gang] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.
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.

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].

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