Internals

DocumenterCitations.CitationBibliographyType

Plugin for enabling bibliographic citations in Documenter.jl.

bib = CitationBibliography(bibfile; style=:numeric)

instantiates a plugin object that must be passed as an element of the plugins keyword argument to Documenter.makedocs.

Arguments

  • bibfile: the name of the BibTeX file from which to read the data.
  • style: the style to use for the bibliography and all citations. The available built-in styles are :numeric (default), :authoryear, and :alpha. With user-defined styles, this may be an arbitrary name or object.

Internal fields

The following internal fields are used by the citation pipeline steps. These should not be considered part of the stable API.

  • entries: dict of citation keys to entries in bibfile
  • citations: ordered dict of citation key to citation number
  • page_citations: dict of page file name to set of citation keys cited on page.
  • anchor_map: an AnchorMap object that keeps track of the link anchors for references in bibliography blocks
source

Citation Pipeline

The DocumenterCitations.CitationBibliography plugin hooks into the Documenter.Builder.DocumentPipeline[1] between ExpandTemplates (which expands @docs blocks) and CrossReferences. The plugin adds the following three steps:

  1. CollectCitations
  2. ExpandBibliography
  3. ExpandCitations
DocumenterCitations.ExpandBibliographyType

Pipeline step to expand all @bibliography blocks.

Runs after CollectCitations but before ExpandCitations.

Each bibliography is rendered into HTML as a a definition list, a bullet list, or an enumeration depending on bib_html_list_style.

For a definition list, the label for each list item is rendered via format_bibliography_label and the full bibliographic reference is rendered via format_bibliography_reference.

For bullet lists or enumerations, format_bibliography_label is not used and format_bibliography_reference fully determines the entry.

The order of the entries in the bibliography is determined by the bib_sorting method for the chosen citation style.

The ExpandBibliography step runs init_bibliography! before expanding the first @bibliography block.

source

Customization

A custom style can be created by defining methods for the functions listed below that specialize for a user-defined style argument to CitationBibliography. If the style is identified by a simple name, e.g. :mystyle, the methods should specialize on Val{:mystyle}, see the examples for custom styles. Beyond that, e.g., if the style needs to implement options or needs to maintain internal state to manage unique citation labels, style can be an object of a custom type. The builtin DocumenterCitations.AlphaStyle is an example for such a "stateful" style, initialized via a custom init_bibliography! method.

DocumenterCitations.format_bibliography_labelFunction

Format the label for an entry in a @bibliography block.

mdstr = format_bibliography_label(style, entry, citations)

produces a plain text (technically, markdown) string for the label in the bibliography for the given Bibliography.Entry. The citations argument is a dict that maps citation keys (entry.id) to the order in which citations appear in the documentation, i.e., a numeric citation key.

For the default style=:numeric, this returns a label that is the numeric citation key in square brackets, cf. format_citation. In general, this function is used only if bib_html_list_style returns :dl for the given style.

source
DocumenterCitations.format_bibliography_referenceFunction

Format the full reference for an entry in a @bibliography block.

mdstr = format_bibliography_reference(style, entry)

produces a markdown string for the full reference of a Bibliography.Entry. For the default style=:numeric, the result is formatted like in REVTeX and APS journals. That is, the full list of authors with initials for the first names, the italicized tile, and the journal reference (linking to the DOI, if available), ending with the publication year in parenthesis.

source
DocumenterCitations.format_citationFunction

Expand a CitationLink into style-specific markdown code.

md_text = format_citation(style, cit, entries, citations)

returns a string of markdown code that replaces the original citation link, rendering it for the given style. The resulting markdown code should make use of direct citation links (cf. DirectCitationLink).

For example, for the default style,

using DocumenterCitations: format_citation, CitationLink, example_bibfile
using Bibliography

cit = CitationLink("[BrifNJP2010, Shapiro2012; and references therein](@cite)")
entries = Bibliography.import_bibtex(example_bibfile)
citations = Dict("BrifNJP2010" => 1, "Shapiro2012" => 2)

format_citation(:numeric, cit, entries, citations)

# output

"[[1](@cite BrifNJP2010), [2](@cite Shapiro2012), and references therein]"

Arguments

  • style: The style to render the citation in, as passed to CitationBibliography
  • cit: A CitationLink instance representing the original citation link
  • entries: A dict mapping citations keys to a Bibliography.Entry
  • citations: A dict mapping that maps citation keys to the order in which citations appear in the documentation, i.e., a numeric citation index.
source
DocumenterCitations.init_bibliography!Function

Initialize any internal state for rendering the bibliography.

init_bibliography!(style, bib)

is called at the beginning of the ExpandBibliography pipeline step. It may mutate internal fields of style or bib to prepare for the rendering of bibliography blocks.

For the default style, this does nothing.

For, e.g., AlphaStyle, the call to init_bibliography! determines the citation labels, by generating unique suffixed labels for all the entries in the underlying .bib file (bib.entries), and storing the result in an internal attribute of the style object.

Custom styles may implement a new method for init_bibliography! for similar purposes. It can be assumed that all the internal fields of the CitationBibliography bib object are up-to-date according to the citations seen by the earlier CollectCitations step.

source

Auxiliary customization routines

The following routines are used by the default styles to implement specific formatting. They may be reused by custom styles.

DocumenterCitations.format_labeled_citationFunction

Format a citation as in a "labeled" style.

md = format_labeled_citation(
    style, cit, entries, citations;
    sort_and_collapse=true,
    brackets="[]",
    names=:lastonly,
    notfound="?",
)

may be used when implementing format_citation for custom styles, to render the given CitationLink object cit in a format similar to the built-in :numeric and :alpha styles.

Options

  • sort_and_collapse: whether to sort and collapse combined citations, e.g. [1-3] instead of [2,1,3]. Not applicable to @citet.
  • brackets: characters to use to enclose citation labels
  • namesfmt: How to format the author names in @citet (:full, :last, :lastonly)
  • notfound: citation label to use for a citation to a non-existing entry

Beyond the above options, defining a custom citation_label method for the style controls the label to be used (e.g., the citation number for the default :numeric style.)

source
DocumenterCitations.format_authoryear_citationFunction

Format a citation as in the :authoryear style.

md = format_authoryear_citation(
    style, cit, entries, citations;
    empty_names="Anonymous",
    empty_year="undated",
    parenthesis="()",
    notfound="???",
)

may be used when implementing format_citation for custom styles, to render the given CitationLink object cit in a format similar to the built-in :authoryear style.

Options

  • namesfmt: How to format the author names (:full, :last, :lastonly)
  • empty_names: String to use as "author" when the entry defines no author
  • empty_year: String to use as "year" when the entry defines no year
  • parenthesis: The parenthesis symbols to use for @cite/@citep
  • notfound: How to render a citation without a corresponding entry
source
DocumenterCitations.citation_labelFunction

Return a citation label.

label = citation_label(style, entry, citations; notfound="?")

returns the label used in citations and the bibliography for the given entry in the given style. Used by format_labeled_citation, and thus by the built-in styles :numeric and :alpha.

For the default :numeric style, this returns the citation number (as found by looking up entry.id in the citations dict) as a string.

May return notfound if the citation label cannot be determined.

source
DocumenterCitations.format_labeled_bibliography_referenceFunction

Format a bibliography reference as in a "labeled" style.

mdstr = format_labeled_bibliography_reference(
    style, entry;
    namesfmt=:last,
    urldate_accessed_on="Accessed on ",
    urldate_fmt=dateformat"u d, Y",
    title_transform_case=(s->s),
    article_link_doi_in_title=false,
)

Options

  • namesfmt: How to format the author names (:full, :last, :lastonly)
  • urldate_accessed_on: The prefix for a rendered urldate field.
  • urldate_fmt: The format in which to render an urldate field.
  • title_transform_case: A function that transforms the case of a Title (Booktitle, Series) field. Strings enclosed in braces are protected from the transformation.
  • article_link_doi_in_title: If false, the URL is linked to the title for Article entries, and the DOI is linked to the published-in. If true, Article entries are handled as other entries, i.e., the first available URL (URL or, if no URL available, DOI) is linked to the title, while only in the presence of both, the DOI is linked to the published-in.
source
DocumenterCitations.format_authoryear_bibliography_referenceFunction

Format a bibliography reference as for the :authoryear style.

mdstr = format_authoryear_bibliography_reference(
    style, entry;
    namesfmt=:lastfirst,
    empty_names="—",
    urldate_accessed_on="Accessed on ",
    urldate_fmt=dateformat"u d, Y",
    title_transform_case=(s->s),
    article_link_doi_in_title=false,
)

Options

  • namesfmt: How to format the author names (:full, :last, :lastonly)
  • empty_names: String to use in place of the authors if there are no authors
  • urldate_accessed_on: The prefix for a rendered urldate field.
  • urldate_fmt: The format in which to render an urldate field.
  • title_transform_case: A function that transforms the case of a Title (Booktitle, Series) field. Strings enclosed in braces are protected from the transformation.
  • article_link_doi_in_title: If false, the URL is linked to the title for Article entries, and the DOI is linked to the published-in. If true, Article entries are handled as other entries, i.e., the first available URL (URL or, if no URL available, DOI) is linked to the title, while only in the presence of both, the DOI is linked to the published-in.
source

Customizing LaTeX output

DocumenterCitations.set_latex_optionsFunction

Set options for how bibliographies are written via Documenter.LaTeXWriter.

DocumenterCitations.set_latex_options(; options...)

Valid options that can be passed as keyword arguments are:

  • ul_as_hanging: If true (default), format unordered bibliography lists (:ul returned by DocumenterCitations.bib_html_list_style) as a list of paragraphs with hanging indent. This matches the recommended CSS styling for HTML :ul bibliographies, see CSS Styling. If false, the bibliography will be rendered as a standard bulleted list.
  • ul_hangindent: If ul_as_hanging=true, the amount of hanging indent. Must be a string that specifies a valid LaTeX length, e.g., "0.33in"
  • dl_hangindent : Bibliographies that should render as "definition lists" (:dl returned by DocumenterCitations.bib_html_list_style) are emulated as a list of paragraphs with a fixed label width and hanging indent. The amount of hanging indent is specified with dl_hangindent, cf. ul_hangindent.
  • dl_labelwidth : The minimum width to use for the "label" in a bibliography rendered in the :dl style.
  • bib_blockformat: A LaTeX format command to apply for a bibliography block. Defaults to "\raggedright", which avoids hyphenation within the bibliography. If set to an empty string, let LaTeX decide the default, which will generally result in fully justified text, with hyphenation.

These should be considered experimental and not part of the the stable API.

Options that are not specified remain unchanged from the defaults, respectively a previous call to set_latex_options.

For bibliography blocks rendered in a :dl style, setting dl_hangindent and dl_labelwidth to the same value (slightly larger than the width of the longest label) produces results similar to the recommended styling in HTML, see CSS Styling. For very long citation labels, it may look better to have a smaller dl_hangindent.

Throws an ArgumentError if called with invalid options.

The defaults can be reset with DocumenterCitations.reset_latex_options.

source
DocumenterCitations.reset_latex_optionsFunction

Reset the options for how bibliographies are written in LaTeX.

DocumenterCitations.reset_latex_options()

is equivalent to the following call to set_latex_options:

set_latex_options(;
    ul_as_hanging=true,
    ul_hangindent="0.33in",
    dl_hangindent="0.33in",
    dl_labelwidth="0.33in",
    bib_blockformat="\raggedright",
)
source

The standard citation links described in Syntax are internally parsed into the DocumenterCitations.CitationLink data structure:

DocumenterCitations.CitationLinkType

Data structure representing a general (non-direct) citation link.

cit = CitationLink(link)

parses the given link string, e.g. "[GoerzQ2022](@cite)".

Attributes

  • node: The MarkdownAST.Node that link parses into
  • keys: A list of BibTeX keys being cited. e.g., ["BrumerShapiro2003", "BrifNJP2010"] for the citation "[BrumerShapiro2003,BrifNJP2010; and references therein][@cite]"
  • cmd: The citation command, one of :cite, :citet, :citep, or (unsupported in the default styles) :citealt, :citealp, :citenum. Note that, e.g., "[Goerz@2022](@Citet*)" results in cite_cmd=:citet
  • note: A citation note, e.g. "Eq. (1)" in [GoerzQ2022; Eq. (1)](@cite)
  • capitalize: Whether the citation should be formatted to appear at the start of a sentence, as indicated by a capitalized @Cite... command, e.g., "[GoerzQ2022](@Citet)"
  • starred: Whether the citation should be rendered in "extended" form, i.e., with the full list of authors, as indicated by a * in the citation, e.g., "[Goerz@2022](@Citet*)"

See also

  • DirectCitationLink – data structure for direct citation links of the form [text](@cite key).
source

Note the this does not include direct citation links such as [the Semi-AD paper](@cite GoerzQ2022), which are instead parsed into DocumenterCitations.DirectCitationLink:

DocumenterCitations.DirectCitationLinkType

Data structure representing a direct citation link.

cit = DirectCitationLink(link)

parses the given link string of the form [text](@cite key).

Attributes

  • node: The MarkdownAST.Node that link parses into
  • key: The BibTeX key being cited. Note that unlike CitationLink, a DirectCitationLink can only reference a single key

See also

  • CitationLink – data structure for non-direct citation links.
source

Debugging

Set the environment variable JULIA_DEBUG=Documenter,DocumenterCitations before generating the documentation.