mini-cite 0.2.0

BibTeX-backed inline citations and footnotes for the mini-* family.
Documentation
# 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

| 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.

```rust
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:

```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).