# mini-cite
A Rust crate for BibTeX-backed inline citations and footnotes in Markdown. Part of the [mini-* family](https://gitlab.com/makeitmini).
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
```toml
[dependencies]
mini-cite = "0.2"
```
## Usage
```rust
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`:
```bibtex
@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:
```markdown
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
| `[@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.
```rust
use mini_cite::CiteStyle;
let style = CiteStyle::default()
.reference_class("citation-marker")
.backlink_label("↑");
```
| `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:
```toml
mini-docs = { version = "0.5", features = ["cite"] }
```
```rust,ignore
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](https://gitlab.com/makeitmini/cite).