Referencing Sections

Using cross-referencing via links works well for HTML or EPUB documents, where you have hypertext, but less well for printed media, where you don’t. There, you would make references to chapters and sections using their numbers instead, but that isn’t supported in standard Markdown.

This approach will use the LaTeX section numbering system for PDF output but will also work for other output formats such as HTML.

This will only affect LaTeX and PDF output, though, and not other output formats.

This will insert chapter and section numbers at the desired depth and let you cross-reference sections in HTML and EPUB format, but unfortunately the cross-referencing does not work in LaTeX and PDF. Here, you only get the section numbers but not the cross-references inserted.

either since both the Pandoc filter and LaTeX will insert section numbers , and you end up with two of them in each header.

Reference Prefixes

For documents where you have both chapters and sections, this might not be what you want. There you might want to use the prefix “Chapter” for chapters and “Section” for sections. Unfortunately, you cannot make prefixes that depend on the header depth, but you can disable the prefixes by overriding them.

You can either change the reference prefix on a per-reference basis or globally through metadata. For referring to chapters as “Chapter” rather than “sec.”—as in this example—the best solution is probably to set the prefix explicitly when referring to a chapter, but we can see how both approaches work.

To use a per-reference specific prefix, you need to insert the prefix you want between the start square bracket and the label. So, to make the prefix for the reference to a chapter be “Chapter,” we would write [Chapter @sec:chapter].

Notice the lack of spaces between prefix and references here. This is needed for PDF output; the LaTeX document that Pandoc generates for the references contain a hard space, so if we put a space between the prefix and reference, the PDF document will have too much space in the generated text. For HMTL and EPUB, it doesn’t matter.

Completely disabling a prefix can be done on a per-reference basis as well. Just add a “-” between the start bracket and the label. If you write [-@sec:chapter], you only get the chapter number and not the prefix. You rarely need to set the default prefix to the empty string explicitly. But using that as an example gave me an excuse to introduce the variable.

The prefix list can have any length, and the number of references is used to select a prefix. So, if you want a special prefix when you refer to three sections, you can add a third element to the list. When you have more references than prefixes, you get the last element in the list. Thus, if you specify two elements in the list, the first is used for singular references and the second for multiple references .

You might want to use lowercase “sect.” when you refer to a section in the middle of a sentence but “Sect.” at the beginning of sentences. With pandoc-crossref it is simple to switch between uppercase and lowercase label prefixes. If you insert a label that starts with an uppercase, your prefix will be in uppercase as well. Thus, if you write [@Sec:label], the default prefix will be “Sec.”; if you write [@sec:label], the default prefix will be “sec.”. The same goes for references to figures, tables, equations, and so on.

Referencing Figures, Tables, and Equations

You cannot put a space between the figure insertion and the label definition. You refer to figure labels as you would with references to sections.

For tables you must have a space between the caption and the label.

You can change the default prefix for figures, tables, and equations, as you can for sections, with the metadata figPrefix, tblPrefix, and eqnPrefix, respectively.

For more details on how to use the cross-reference filter, I will refer to its online manual.⁴

Bibliographies

The two filters use similar kinds of citation syntax, and this means that the order in which you run the filters matter. The citeproc filter gets confused if it sees cross-reference labels. The same does not happen if you run the cross-reference filter first; it will leave the citation codes alone so they can be handled by the citation filter.

The pandoc-citeproc filter can read bibliographies in various file formats and will pick the format based on the file suffix. With .bib files it will use BibTeX. For EndNote you would use .enl and for ISI .wos. Check the online documentation⁵ for a complete list.

To control the format used for citations and the bibliography, you can specify a CSL⁶ file with the metadata variable csl or the Pandoc option --csl. CSL files for most journal styles can be downloaded from GitHub.⁷

For example, if “smith12” is a key in your bibliography, you can insert a citation using [@smith12]. You need to include @ even though it isn’t part of the reference key; the filter (and Pandoc) uses this to recognize citations. You can cite more than one reference by separating the references with semicolons: [@smith12; @smith14].

Depending on the citation style, the inserted reference might contain author names. This doesn’t read well if you have already mentioned authors in the text, and you can disable it with a minus before the reference: [-@smith12]. The same effect is achieved by leaving out the square brackets and write @smith12.

More generally, you can insert text in the citations to add, for example, page information or other comments, such as [see @smith12, chap1; also @smith14, chap 12]. If you leave out the square brackets to get an in-text citation, you can add comments to appear inside the parenthesis (again, depending on your citation style) by writing the comments in square brackets after the reference: see @smith12 [chapter 11].

The bibliography will be put at the end of your document. If you want to give the bibliography a section header, you should end your Markdown document with the header for the bibliography.

Exercises