mini-cite 0.2.0

BibTeX-backed inline citations and footnotes for the mini-* family.
Documentation
  • Coverage
  • 100%
    24 out of 24 items documented2 out of 4 items with examples
  • Size
  • Source code size: 95.6 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 503.4 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 3s Average build duration of successful builds.
  • all releases: 4s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • Repository
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • parchment

mini-cite

A Rust crate for BibTeX-backed inline citations and footnotes in Markdown. Part of the mini-* family.

Pairs a directory of .bib files with Pandoc-style [@key] citations: each citation becomes a numbered footnote reference, and a matching footnote block is appended to the document.

Installation

[dependencies]
mini-cite = "0.2"

Usage

use mini_cite::{process, Bibliography, CiteStyle};

let bibliography = Bibliography::load_dir("bib")?;
let style = CiteStyle::default();
let output = process("Small things matter [@smith2020].", &bibliography, &style)?;
# Ok::<(), mini_cite::CiteError>(())

Given bib/refs.bib:

@article{smith2020,
  author = {Jane Smith},
  title = {On Small Things},
  journal = {Journal of Minimal Systems},
  year = {2020}
}

the output is the original Markdown with the citation rewritten and a footnote block appended:

Small things matter <sup id="fnref-1" class="footnote-ref"><a href="#fn-1">1</a></sup>.

<hr class="footnotes-sep">
<ol class="footnotes">
<li id="fn-1" class="footnote">Jane Smith. On Small Things. Journal of Minimal Systems. 2020. <a href="#fnref-1" class="footnote-back">↩</a></li>
</ol>

The result is Markdown with raw HTML embedded, not finished HTML — the caller still renders it.

Citation syntax

Written Meaning
[@key] One citation
[@first;second] Two citations in one place
[@first; @second] The same, spaced form

Rules:

  • Numbered by first appearance. A key cited more than once keeps its first number instead of claiming a second footnote. Each occurrence still gets a unique element id (fnref-1, fnref-1-2, …) so the HTML stays valid; the footnote's back-link targets the first.
  • Code is left alone. Citations inside fenced code blocks and inline code spans are never rewritten, so a code sample demonstrating this syntax survives it.
  • Unknown keys fail loudly. A citation naming a key no .bib file defines is an error, not a silent pass-through. Processing stops at the first one.
  • A document with no citations is returned unchanged, byte for byte.

Bibliography loading

Bibliography::load_dir reads every *.bib file directly inside a directory (non-recursive), in sorted filename order, and merges them into one set of keys. A key defined by two files is an error naming both. A directory with no .bib files loads to an empty bibliography rather than failing.

Styling

CiteStyle names the class on each emitted element and the back-link's label. The markup's structure and its fn-N/fnref-N ids are fixed — only the parts a stylesheet addresses are configurable.

use mini_cite::CiteStyle;

let style = CiteStyle::default()
    .reference_class("citation-marker")
    .backlink_label("↑");
Setter Element Default
reference_class <sup> around an inline reference footnote-ref
separator_class <hr> opening the block footnotes-sep
list_class <ol> of footnotes footnotes
item_class each footnote <li> footnote
backlink_class the back-link <a> footnote-back
backlink_label the back-link's text ↩

Defaults follow Pandoc's names, so a stylesheet written against Pandoc's footnote output mostly applies unchanged. Setting a class to "" emits that element with no class attribute at all, for callers styling structurally (li[id^="fn-"]) instead.

The back-link label is written into the document verbatim, so markup in it reaches the renderer as markup and is subject to whatever sanitizing follows.

Use with mini-docs

mini-docs exposes this crate as a MarkdownProcessor behind its cite feature:

mini-docs = { version = "0.5", features = ["cite"] }
use mini_docs::{Builder, CiteProcessor, CiteStyle};

Builder::new("content")
    .templates("templates")
    .output("public")
    .default_template("page.html")
    .processor(CiteProcessor::new("bib")?.with_style(CiteStyle::default().backlink_label("↑")))
    .build()?;

The bibliography is read once, when the processor is constructed, so a malformed or ambiguous .bib directory fails before any page is built. A .bib file edited during a Watcher session is not picked up until the session restarts — Watcher rebuilds on .md and template changes only.

The emitted markup uses only <sup>, <a>, <hr>, <ol>, and <li> with id/href/class attributes, all of which survive mini-docs' default ammonia sanitization intact. Against a stricter sanitizer the classes may be dropped — ammonia's own default policy strips class, and mini-docs allowlists it from 0.5.0 on. The ids survive either way.

BibTeX support

Supports what real-world .bib files rely on: @type{key, field = {value}, field = "value"} entries, brace-nested values, quoted and bare values, multi-line values, trailing commas, and mixed-case field names (normalized to lowercase). @comment and @string blocks are parsed and discarded; text between entries is skipped.

Not supported: @string macro expansion, crossref inheritance, and TeX accent-escape resolution. Braces inside a value are treated as capitalization hints and removed, since they carry no meaning in HTML output.

Citation style

Deliberately style-agnostic — there is no CSL engine, and every entry type renders the same way: author, title, journal, publisher, year, joined by periods. Absent fields are skipped without leaving stray punctuation. An entry with none of those fields falls back to its citation key rather than rendering empty.

License

MIT

Contributing

Issues and pull requests welcome on GitLab.