CSS Styling

For an optimal rendering of the bibliography, DocumenterCitations ships with a stylesheet citations.css containing

.citation dl {
  display: grid;
  grid-template-columns: max-content auto; }
.citation dt {
  grid-column-start: 1; }
.citation dd {
  grid-column-start: 2;
  margin-bottom: 0.75em; }
.citation ul {
 padding: 0 0 2.25em 0;
 margin: 0;
 list-style: none !important;}
.citation ul li {
 text-indent: -2.25em;
 margin: 0.33em 0.5em 0.5em 2.25em;}
.citation ol li {
 padding-left:0.75em;}
.citation .citation-backlinks a {
 white-space: nowrap;
 text-decoration: none;}
.citation .citation-backlinks a.is-current-citation {
 outline: 1px solid currentColor;
 border-radius: 3px;}

Note

As of DocumenterCitations v1.5, the above stylesheet is injected automatically (by the DocumenterCitations.InjectAssets pipeline step) for any documentation that uses the CitationBibliography plugin. In previous versions, citations.css had to be created manually and added to the assets entry in makedocs. When transitioning from v1.4 to v1.5, you should delete an unmodified citations.css from assets.

The HTML generated by DocumenterCitations also uses CSS classes canonical and noncanonical to distinguish between canonical and non-canonical blocks. While these are not used in the above citations.css, custom CSS could implement different formatting for the two types of bibliographies.

To adapt or override the default styling, place a file citations.css (or any other name) in the docs/src/assets folder of your project, and list it as an asset for Documenter.HTML in your docs/make.jl:

makedocs(;    format = Documenter.HTML(        # ...        assets=String["assets/citations.css"],    ),    plugins=[bib],    # ...)

Since the bundled stylesheet is inserted before any user-defined assets, the rules in such a file take precedence over the default styling. However, rules from the built-in and the custom stylesheet are still combined. To take full control of the styling, instantiate the plugin with insert_css=false:

bib = CitationBibliography("src/refs.bib"; insert_css=false)

This prevents the bundled stylesheet from being copied into the build folder or being referenced in the generated HTML, leaving a manually declared CSS file in the assets of Documenter.HTML as the only source of styling.

Warning

Only have a citations.css file in the assets list if you intend to customize the styling of the bibliography. Be deliberate about whether your customization augments the built-in styles (e.g., to customize non-canonical bibliographies), or replaces them, and set the insert_css flag accordingly.

Citation hover popups

Hovering over (or tabbing to) a citation link shows the bibliography entry in a popup, in the same form in which it appears in the @bibliography block that defines it. This saves the reader from leaving the current page, and ties in with the footnote previews that Documenter shows for footnote links. The popup stays open while the mouse is over it, so that long entries can be scrolled and links inside them can be clicked. Pressing Escape closes it. Try hovering over the citation of Ref. [2].

The popups are styled by the bundled citations-hover.css, which defines the .citation-hover-popup class and a set of --citation-hover-* custom properties for the colors of the built-in Documenter themes. As for citations.css, a custom stylesheet in the assets of Documenter.HTML takes precedence. To disable the popups entirely:

bib = CitationBibliography("src/refs.bib"; show_hover=false)

This is independent of the insert_css option.

Bibliography backlinks

Every entry in a canonical @bibliography block ends with a list of backlinks (↩) to the places where the reference is cited, in the order in which the citations appear in the documentation. Hovering over a backlink names the section it leads to. See the References for how this looks for a reference that is cited a few dozen times.

After following a citation, the backlink that leads back to it is outlined, so that it can be picked out among the others. The outline is applied by the bundled citations-backlinks.js, which adds the class is-current-citation to that backlink; the styling is part of citations.css. Readers without JavaScript, and readers who reach the bibliography by other means than following a citation, see all backlinks alike. To omit the backlinks:

bib = CitationBibliography("src/refs.bib"; show_backlinks=false)

The backlinks are an HTML feature: they never appear in the LaTeX output.