# Citum Engine
The core citation and bibliography processing engine for Citum.
## Document Input Formats
The engine supports two document input formats for the `process_document` pipeline.
These are independent from the **document output format** (such as HTML, Plain, LaTeX, Typst, Djot, Markdown)
and from **reference field inline markup** (Djot inline in `title`, `annotation`, and
`note` fields via `render_djot_inline`).
### Djot
Full-featured adapter. In addition to citation parsing, the Djot adapter supports:
- YAML frontmatter (bibliography groups, integral-name overrides)
- Manual footnotes (note-style placement into authored `[^label]:` blocks)
- Inline bibliography blocks (`:::bibliography`)
- Djot-to-HTML finalization via `jotdown`
#### Citation Syntax
| `[@key]` | Basic parenthetical citation | (Smith, 2023) |
| `[@key1; @key2]` | Multiple citations | (Smith, 2023; Jones, 2022) |
| `[prefix ; @key1; @key2]` | Global prefix | (see Smith, 2023; Jones, 2022) |
| `[@key1; @key2 ; suffix]` | Global suffix | (Smith, 2023; Jones, 2022 for more) |
| `[prefix ; @key1; @key2 ; suffix]` | Both global affixes | (see Smith, 2023; Jones, 2022 for more) |
**Note on Semicolons**: Global affixes must be separated from cite keys by a semicolon `;`.
#### Narrative (Integral) Citations
Narrative citations are integrated into the text flow using the `+` mode modifier. For numeric styles, these render as **Author [1]**.
| `[+@key]` | Explicit narrative | Smith (2023) |
#### Modifiers
Modifiers appear immediately before the `@` symbol.
| `-` | Visibility | Suppress Author | `[-@key]` | (2023) |
| `+` | Mode | Integral / Narrative | `[+@key]` | Smith (2023) |
| `!` | Visibility | Hidden (Nocite) | `[!@key]` | *bibliography only* |
#### Locators (Pinpoints)
Locators follow a comma after the citekey.
| **Page** | `[@key, 45]` or `[@key, p. 45]` | (Smith, 2023, p. 45) |
| **Chapter** | `[@key, ch. 5]` | (Smith, 2023, ch. 5) |
| **Structured** | `[@key, chapter: 2, page: 10]` | (Smith, 2023, chap. 2, p. 10) |
Bare locator values default to `page`.
#### Complex Examples
- **Explicit narrative**: `[+@smith2023]` → Smith (2023)
- **Mixed visibility**: `[see ; -@smith2023, p. 45; @jones2022]` → (see 2023, p. 45; Jones, 2022)
- **Global affixes**: `[compare ; @kuhn1962; @watson1953 ; for discussion]` → (compare Kuhn, 1962; Watson & Crick, 1953 for discussion)
---
### Markdown (Pandoc-style)
Lightweight adapter for Markdown documents that use Pandoc-style citation markers.
Supports inline prose citations only. Frontmatter, manual footnotes, and inline
bibliography blocks are not supported in this adapter (v1).
HTML output is **not** post-processed by this adapter — the caller receives the
citation-substituted Markdown markup and is responsible for any subsequent
CommonMark-to-HTML conversion.
#### Citation Syntax
| `[@key]` | Parenthetical citation |
| `[@key1; @key2]` | Multi-cite cluster |
| `[-@key]` | Suppress-author citation |
| `@key` | Textual (narrative/integral) citation |
| `@key [p. 45]` | Textual citation with bracketed locator |
| `[@key, p. 45]` | Parenthetical citation with locator |
The Pandoc citation syntax is syntactically very similar to Djot's — both formats
share `@key` as the citation token and `[...]` for grouping. The Markdown adapter
intentionally supports the common subset; Djot-specific modifiers (`+`, `!`) are
not part of Pandoc syntax and are not supported here.
---
## Reference Field Inline Markup
Inline markup in bibliographic data fields (`title`, `annotation`, `note`) is a
**separate concern** from document input format. Field markup uses Djot inline
syntax via `render_djot_inline`, regardless of which document input format is in use.
See `docs/architecture/DJOT_RICH_TEXT.md` for details.