Writing Citation-Enabled Posts in Persona

Persona uses Pandoc to turn citation keys into linked, formatted citations and a bibliography during the build. This guide covers setup, authoring, and previewing a citation-enabled post (Zola themes). The workflow suits technical, research, and reference-heavy writing.

Requirements and setup

Install Pandoc and watchexec:

# macOS
brew install pandoc watchexec

# Ubuntu / Debian
sudo apt install pandoc
cargo install watchexec-cli

From your site root, copy the build scripts and Makefile from the theme:

cp -r themes/persona/{scripts,Makefile} .

Add this to config.toml so Zola skips the authoring sources and citation data:

ignored_content = ["*.src.md", "*.bib", "*.csl"]

Write a post

Keep the source, bibliography, and generated Markdown in the same folder:

• index.src.md is the authoring source.
• references.bib stores the BibTeX entries.
• index.md is generated by Pandoc; edit the source instead.

Write citations in .src.md

Use Pandoc citation syntax in Markdown:

Climate change is accelerating[@ipcc2021].
Multiple studies confirm this[@ipcc2021; @nasa2023].

Add citation settings to the post’s [extra] front matter:

• citation_style = "apa"
• bibliography = "references.bib"

Set the citation style once for the site if you want it to apply to posts by default.

Mathematics and LaTeX macros

Define reusable KaTeX macros in [extra.tex.macros]. TOML literal strings preserve backslashes:

[extra.tex.macros]
'\Real' = '\mathbb{R}^{#1}'
'\norm' = '\left\lVert #1 \right\rVert'

For a vector \(x \in \Real{n}\), the Euclidean norm is

\[ \norm{x}_2 = \sqrt{\sum_{i=1}^{n} x_i^2}. \]

Write inline mathematics between $ delimiters and display mathematics between $$ delimiters. Pandoc preserves the expressions for KaTeX, including these page-specific macros. Citation references and mathematics can appear together in the same article (Zola themes).

Build and preview

Use the copied Makefile to build or preview your site:

make build
make serve

make build converts changed .src.md files into .md files; run zola build to generate the site. make serve watches the sources and dependencies, rebuilds when needed, and runs zola serve. The incremental build checks the scripts, configuration, bibliography, and CSL files. Generated .md files do not trigger another rebuild.

To rerun preprocessing after changing the pipeline, run bash scripts/build.sh from your site root. If you use the scripts directly from the installed theme, run bash themes/persona/scripts/build.sh from the site root.

Citation style resolution order

The preprocessor selects a CSL style in this order:

1. The post’s [extra].citation_style, resolved from citation-style/<name>.csl.
2. A style.csl beside the .src.md file.
3. Site config.toml: [extra].citation_style or [extra.persona].citation_style.
4. Theme themes/persona/theme.toml [extra].citation_style, or themes/persona/config.toml [extra.persona].citation_style.

Persona includes the ieee and apa styles. Add custom CSL files to your site’s citation-style/ directory or place a style.csl beside a post source. If a named post style cannot be found, the preprocessor warns and falls back to the configured default. The build script requires a site or theme default style.

Output and styling

Pandoc emits HTML citations and a bibliography with stable classes that the theme styles:

• .citation
• .references
• .csl-entry
• .csl-left-margin
• .csl-right-inline

Inline citations link to their bibliography entries. The bibliography appears inside the references container under Bibliography, after the optional Citation section. That section displays the post’s [extra.post].bibtex; the bibliography lists works cited in the text. This guide includes a sample BibTeX record to demonstrate both.

For the complete example, see this guide’s source directory.