citum-engine

citum-engine is the Rust citation and bibliography processor for Citum. Use it when your application already has, or can load, Citum styles, reference data, and citation occurrences, and needs formatted citations or bibliographies as plain text, HTML, Djot, LaTeX, or Typst.

The engine is intentionally narrower than the full Citum application stack. It does not manage registries, fetch remote styles, or persist user data. Those responsibilities belong in adapters such as a CLI, server, editor integration, or application-specific resolver.

Installation

[dependencies]
citum-engine = "0.53"

# Optional, but recommended when loading bibliography files.
citum-io = "0.53"

Default features include icu, which enables ICU-backed collation and locale support used by sorting and rendering. Optional features:

Which API to Use

Most integrations should start with the document-level API:

• format_document resolves a local style from StyleInput::Path or StyleInput::Yaml, then formats ordered citation occurrences and a bibliography.
• format_document_with_style takes an already resolved Style as its first argument, plus the same FormatDocumentRequest shape. Use this when your application has its own style resolver, registry, cache, or embedded style bundle.

Use Processor directly when you need lower-level control over individual citations, bibliography rendering, output-format generics, locales, or parsed document pipelines.

The Processor::process_document path is an advanced document parser pipeline for Djot and a common subset of Pandoc-style Markdown citation syntax. If your application already parses a document into citation occurrences, prefer format_document or format_document_with_style.

Quick Start

This example uses the document-level API with a local Citum style file and citum-io for bibliography loading. citum-io::load_bibliography supports Citum YAML, Citum JSON, Citum CBOR, and CSL-JSON bibliography files.

use citum_engine::{
    format_document, Bibliography, CitationOccurrence, CitationOccurrenceItem,
    FormatDocumentRequest, OutputFormatKind, StyleInput,
};
use citum_io::load_bibliography;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let refs: Bibliography = load_bibliography(Path::new("references.json"))?;

    let request = FormatDocumentRequest {
        style: StyleInput::Path("styles/apa-7th.yaml".to_string()),
        locale: None,
        output_format: OutputFormatKind::Html,
        refs,
        citations: vec![CitationOccurrence {
            id: "cite-1".to_string(),
            items: vec![CitationOccurrenceItem {
                id: "kuhn1962".to_string(),
                locator: None,
                prefix: None,
                suffix: None,
                integral_name_state: None,
            }],
            mode: None,
            note_number: None,
            suppress_author: None,
            grouped: None,
            prefix: None,
            suffix: None,
        }],
        document_options: None,
    };

    let result = format_document(request)?;

    for citation in result.formatted_citations {
        println!("{}: {}", citation.id, citation.text);
    }

    println!("{}", result.bibliography.content);

    for warning in result.warnings {
        eprintln!("{}: {}", warning.code, warning.message);
    }

    Ok(())
}

If your application resolves styles before calling the engine, parse or load the style into citum_schema::Style and call format_document_with_style(style, request) instead. StyleInput::Id and StyleInput::Uri are accepted in request types for adapter compatibility, but format_document cannot resolve them by itself. format_document_with_style still requires FormatDocumentRequest.style to be populated; callers usually keep the original StyleInput there for serialization or diagnostics, while the function renders with the explicit Style argument.

Inputs and Outputs

The document-level API expects:

The result contains formatted citations, a formatted bibliography, per-entry bibliography metadata, and structured warnings. Missing references and forward-compatible unknown values are reported as warnings where rendering can continue.

Boundaries

• The engine does not fetch remote styles, access registries, or resolve style IDs and URIs. Resolve those before calling format_document_with_style, or use another Citum adapter that provides a resolver chain.
• format_document uses the built-in en-US locale. A non-en-US locale tag currently produces a warning and falls back unless the caller uses lower-level APIs with a resolved locale.
• Markdown document parsing supports the common Pandoc-style citation subset listed below. It does not implement all Djot document features.
• Inline markup inside bibliographic fields such as title, annotation, and note is Djot-based and independent from the document input format.

Document Syntax

The engine supports two document input formats for the process_document pipeline. These are independent from the document output format and from reference-field inline markup.

Djot

The Djot adapter supports citation parsing plus:

• YAML frontmatter for bibliography groups and integral-name overrides
• manual footnotes for note-style placement into authored [^label]: blocks
• inline bibliography blocks with :::bibliography
• Djot-to-HTML finalization via jotdown

Citation Syntax

Global affixes must be separated from cite keys by a semicolon (;).

Narrative Citations

Narrative citations are integrated into the text flow using the + mode modifier. For numeric styles, these render as Author [1].

Modifiers

Modifiers appear immediately before the @ symbol.

Locators

Locators follow a comma after the cite key. Bare locator values default to page.

Complex Examples

• [+@smith2023] renders as Smith (2023).
• [see ; -@smith2023, p. 45; @jones2022] renders as (see 2023, p. 45; Jones, 2022).
• [compare ; @kuhn1962; @watson1953 ; for discussion] renders as (compare Kuhn, 1962; Watson & Crick, 1953 for discussion).

Markdown (Pandoc-style)

The Markdown adapter supports inline prose citations using a common subset of Pandoc-style citation markers. Frontmatter, manual footnotes, and inline bibliography blocks are not supported by this adapter.

HTML output is not post-processed by the Markdown adapter. Callers receive citation-substituted Markdown and are responsible for any later CommonMark to HTML conversion.

Citation Syntax

Djot and Pandoc-style Markdown both use @key as the citation token and [...] for grouping. The Markdown adapter intentionally supports the common subset; Djot-specific modifiers such as + and ! are not part of Pandoc syntax and are not supported there.

Related Crates

• citum-schema provides the shared style and reference data model.
• citum-cli provides the citum command-line interface.
• citum-server and citum-bindings are adapter surfaces that build on the engine API.

License

Dual-licensed under MIT or Apache-2.0 at your option.