Examples | Citum

description

Document Processing

Citum can process full documents by extracting citations using a high-performance winnow parser. It supports the draft Djot citation syntax, including multi-cites and narrative (integral) modes.

Djot Input (paper.djot)

According to @kuhn1962[p. 10], revolutions are...
Multi-cite: [see ;@kuhn1962; @watson1953, chapter: 2].
Structured: [@kuhn1962, section: 5].

Rendered Output (Plain Text)

According to Kuhn (1962, p. 10), revolutions are...
Multi-cite: (see Kuhn, 1962; Watson & Crick, 1953, ch. 2).

auto_awesome

Advanced Citations

Citum supports sophisticated citation patterns, including narrative (integral) vs. parenthetical (non-integral) modes, mid-citation "infix" text, and context-aware conjunctions (e.g., APA's "and" vs. "&").

Mode-Dependent Conjunctions (APA Style)

options:
  contributors:
    and: !mode-dependent
      integral: text      # "Smith and Jones (2024)"
      non-integral: symbol  # "(Smith & Jones, 2024)"

Template Contexts & Infix Support

citation:
  integral:
    template:
      - contributor: author
      - variable: infix        # Renders @smith(argues) as "Smith argues..."
        prefix: " "
      - date: issued
        wrap: parentheses
        prefix: " "

Rendered Examples (Draft Djot Syntax)

Narrative with Infix

Source: @kuhn1962(notes that)[p. 10]

Kuhn notes that (1962, p. 10)

Narrative (Multiple Authors)

Source: @weinberg1971

Weinberg and Freedman (1971)

Parenthetical (APA Conjunction)

Source: [@weinberg1971]

(Weinberg & Freedman, 1971)

Multi-cite (Parenthetical)

Source: [@kuhn1962; @weinberg1971]

(Kuhn, 1962; Weinberg & Freedman, 1971)

library_books

Bibliography Grouping

Divide bibliographies into labeled sections with distinct sorting rules. Essential for legal hierarchies (Bluebook), multilingual bibliographies, and primary/secondary source divisions.

Legal Hierarchy (Type-Based Grouping)

bibliography:
  groups:
    - id: primary-legal
      heading: "Primary Sources"
      selector:
        type: [legal-case, statute, treaty]
      sort:
        template:
          - key: type
            order: [legal-case, statute, treaty]
          - key: issued

Explicit type ordering ensures legal-case appears before statute, regardless of alphabetical content.

Multilingual (Per-Group Name Ordering)

bibliography:
  groups:
    - id: vietnamese
      heading: "Tài liệu tiếng Việt"
      selector:
        field:
          language: vi
      sort:
        template:
          - key: author
            sort-order: given-family  # Vietnamese convention

    - id: western
      heading: "Western Sources"
      selector:
        not:
          field:
            language: vi
      sort:
        template:
          - key: author
            sort-order: family-given  # Western convention

Vietnamese names use given-family ordering, Western names use family-given ordering.

Localized Disambiguation (Per-Group Year Suffixes)

bibliography:
  groups:
    - id: cited
      heading: "Cited Works"
      disambiguate: locally  # Reset suffixes for this group
      selector:
        status: visible

    - id: reading
      heading: "Further Reading"
      disambiguate: locally  # Start fresh from "a"
      selector:
        status: silent

Isolating disambiguation prevents collisions across bibliography sections, allowing independent suffix assignment in each group.

lightbulb

Key Features: First-match semantics prevent duplication. Selectors support type matching, field matching (language, keywords), citation status (visible/silent), and negation for fallback groups. See design document for full details.

terminal

Try It Yourself

Render a grouped bibliography with primary, archival, and secondary sources in English:

citum render refs \
  -b examples/bib-grouping-refs.yaml \
  -s styles/chicago-author-date.yaml

Expected output with English headings:

# Primary Sources

Darwin, Charles. 1859. On the Origin of Species. London: John Murray.

Freud, Sigmund. 1900. Die Traumdeutung. Leipzig: Franz Deuticke.

# Archival Sources

Darwin, Charles. 1876. Letter to T.H. Huxley, 14 September 1876.

# Secondary Sources

Browne, Janet. 2002. Charles Darwin: The Power of Place. New York: Alfred A. Knopf.

Gay, Peter. 1988. Freud: A Life for Our Time. New York: W.W. Norton.

Mayr, Ernst. 1991. "Darwin's Impact on Modern Thought." Proceedings of the American Philosophical Society 135 (4): 317–330.

Switch to German headings by setting default-locale: de-DE in the style:

citum render refs \
  -b examples/bib-grouping-refs.yaml \
  -s styles/chicago-author-date.yaml \
  --default-locale de-DE

Expected output with German headings (Primärquellen, Sekundärquellen, Archivalische Quellen).

translate

Multilingual Support

Citum handles multilingual metadata with BCP 47 language tags, supporting original scripts, transliterations (Pinyin, Hepburn, ALA-LC), and translations. Styles declaratively specify rendering preferences with automatic fallback.

Style Configuration

options:
  multilingual:
    title-mode: transliterated  # primary | transliterated | translated | combined
    name-mode: transliterated
    preferred-script: Latn       # Latin script for romanization

Reference Data (YAML)

id: war-peace-zh
type: book
title:
  original: "战争与和平"
  lang: "zh"
  transliterations:
    zh-Latn-pinyin: "Zhànzhēng yǔ Hépíng"
  translations:
    en: "War and Peace"
author:
  original:
    family: "Толстой"
    given: "Лев"
  lang: "ru"
  transliterations:
    Latn:
      family: "Tolstoy"
      given: "Leo"

Rendered Output by Mode

Primary Mode

战争与和平. Лев Толстой (1869)

Original scripts preserved

Transliterated Mode

Zhànzhēng yǔ Hépíng. Leo Tolstoy (1869)

Romanized for Western readers

Translated Mode

War and Peace. Leo Tolstoy (1869)

English translation when available

Combined Mode

Zhànzhēng yǔ Hépíng [War and Peace]. Leo Tolstoy (1869)

Both romanization and translation

info

BCP 47 Fallback Strategy:
1. Exact tag match ("ja-Latn-hepburn")
2. Substring match ("Latn" matches any Latin script)
3. Fallback to original field

terminal

Try It Yourself

Render multilingual references with configurable title and name modes:

citum render refs \
  -b examples/multilingual-refs.yaml \
  -s styles/experimental/multilingual-academic.yaml

Try adjusting the style's title-mode option (primary, transliterated, translated, combined) to see how rendered output changes without modifying reference data.

event

Advanced Dates

Citum supports native EDTF (Extended Date/Time Format) for handling complex historical ranges, uncertain or approximate dates, and seasons.

Date Intervals (Level 0)

issued: "2023-05/2024-06"  # Closed interval
issued: "2023-05/.."        # Open start
issued: "../2023-05"        # Open end

Uncertain & Approximate (Level 1)

issued: "2004?"              # Uncertain year (2004?)
issued: "2004~"              # Approximate year (ca. 2004)
issued: "2004%"              # Uncertain & approximate
issued: "2004-06-11?"        # Uncertain day only

Seasons (Level 1)

issued: "2023-21"           # Spring 2023
issued: "2023-22"           # Summer 2023
issued: "2023-23"           # Autumn 2023
issued: "2023-24"           # Winter 2023

Unspecified Digits (Level 1)

issued: "199u"              # Some time in the 1990s
issued: "2004-uu-uu"        # Some time in 2004 (month/day unknown)

history_edu

Fidelity First: Unlike CSL 1.0's structured date objects, Citum uses EDTF strings as the primary exchange format, ensuring that semantic nuances like "approximate" or "unspecified" are preserved and can be localized by the processor according to the style's locale.

tune

Options-Level Presets

Common configuration patterns for contributors, dates, and titles can be expressed as a single preset name instead of spelling out every field. Mix preset shorthand with explicit overrides for maximum clarity and concision.

# Named presets replace verbose config blocks
options:
  contributors:            # Explicit config (verbose)
    display-as-sort: all
    initialize-with: ". "
    delimiter: ", "
    and: symbol
  dates: long              # Preset shorthand
  titles: apa             # Preset shorthand

# Available presets:
#   contributors: apa | chicago | harvard | ieee | springer | vancouver | numeric-compact | numeric-medium
#   dates:        long | short | numeric | iso
#   titles:       apa | chicago | humanities | ieee | journal-emphasis | scientific
#   substitute:   standard | editor-* | editor-translator-* | editor-title-* | editor-translator-title-*
#   citation:     use-preset: numeric-citation

title

Titles & Links

Citum separates title content from its role (primary, parent-monograph, parent-serial) and uses declarative global formatting rules for consistency across item types.

Global Formatting (options.titles)

titles:
  monograph:
    emph: true      # Italics for books
  periodical:
    emph: true      # Italics for journals
  component:
    emph: false     # Plain for articles

Template Usage & Links

template:
  - title: primary
    links:
      target: doi
      anchor: component
  - title: parent-serial
    suffix: ","

settings_input_component

Type-Specific Overrides

Avoid complex conditional logic. Components in Citum can declaratively override their behavior or suppress themselves based on the item type. Use concise list syntax to apply the same rule to multiple types.

bibliography:
  template:
    - variable: publisher
      overrides:
        [article-journal, webpage, broadcast]: { suppress: true }
    - number: pages
      overrides:
        [chapter, report, entry-encyclopedia]:
          prefix: "pp. "
          wrap: parentheses

html

Pluggable Output Formats

Citum supports multiple output formats with a pluggable architecture. Generate semantic HTML, native LaTeX, flexible Djot for static site generators, or clean Plain Text.

Plain Text (-f plain)

Smith, J. A. (2023). The Future of Citations. Academic Press.

Native LaTeX (-f latex)

Smith, J. A. (2023). \textit{The Future of Citations}. Academic Press.

Semantic HTML (-f html)

<span class="citum-entry">
  <span class="citum-author">Smith, J. A.</span> (2023).
  <i class="citum-title">The Future of Citations</i>. Academic Press.
</span>

Djot (-f djot)

[Smith, J. A.]{.citum-author} (2023). _The Future of Citations_{.citum-title}. Academic Press.

rocket_launch

Consistent Rendering: The pluggable renderer system ensures that complex CSL rules (sorting, disambiguation, name formatting) are applied identically regardless of the output target. LaTeX support includes native escaping for TeX special characters.

integration_instructions

LuaLaTeX Integration Proof-of-concept

A single-pass LuaLaTeX citation workflow backed by the Citum Rust processor via C-FFI. No Biber, no .bbl file, no external bibliography step. The processor runs inline during compilation via LuaJIT FFI, and all Citum output rules (disambiguation, name formatting, et-al) apply identically.

.tex \cite{key}
  └─► \directlua ──► citum-cli.lua (LuaJIT FFI) ──► libcsln_processor (Rust)
                                                       │
                       tex.sprint(rendered) ◄──────────┘

Package Usage (citum-cli.sty)

% Load with your YAML style and bibliography
\usepackage[style=styles/apa-7th.yaml,bibfile=refs.yaml]{citum-cli}

% Non-integral (parenthetical)
\cite[p.~10]{kuhn1962}               % → (Kuhn, 1962, p. 10)

% Integral (narrative)
\textcite{weinberg1971}              % → Weinberg and Freedman (1971)

% Multi-key parenthetical
\cites{kuhn1962, watson1953}          % → (Kuhn, 1962; Watson & Crick, 1953)

% Print bibliography
\printbibliography

Build Instructions

# 1. Build the shared library
$ cargo build -p citum_engine --release --features ffi

# 2. Compile your document
$ CITUM_LIB=$(pwd)/target/release lualatex --shell-escape paper.tex

science

Proof-of-concept status: Currently targets macOS and Linux. A full working example document is available in bindings/latex/. The & conjunction in two-author citations is correctly escaped for LuaLaTeX output.

speed

Binary Performance (CBOR)

For production environments, Citum styles and bibliographies can be compiled into binary CBOR (Concise Binary Object Representation) for near-instant loading.

Compilation

$ citum convert styles/apa-7th.yaml --output /tmp/apa-7th.cbor

Binary formats can reduce parse overhead for large styles and bibliographies.

Processing

$ citum render refs -b data.cbor -s style.cbor

Full binary pipeline for maximum throughput.

schema

Schema Generation

Citum can generate JSON Schemas for its configuration formats, enabling rich IDE support, validation, and auto-completion in editors like VS Code.

Generation Command (Optional Feature)

$ cargo run --bin citum --features schema -- schema > citum.schema.json

Use this only when generating schemas locally; published schemas are already available on the project website.

mouse

Web Interactivity

Citum provides optional JS/CSS assets that enrich semantic HTML output with interactive behaviors. They target data attributes injected by the processor, providing a progressive enhancement layer for web-based citation views.

Explore Enhancements auto_fix_high

Bidirectional Navigation

Click a citation to scroll to its bibliography entry. Hover an entry to highlight all its citations in the document.

Hover Tooltips

Instant reference previews on citation hover, utilizing metadata attributes stored directly in the entry container.

Sidebar Layouts

Optimized for note-style documents. Bibliographies can be pulled into a sticky sidebar on large screens.

Theming

Fully customizable via CSS variables. Includes high-contrast support and clean print styles.

Quick Start Integration

To add interactivity to your own site, simply include the following tags in your HTML. These link to the latest assets via the JSDelivr CDN.

1. CSS (Place in <head>)

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/citum/citum-core@main/docs/assets/citum-interactive.css">

2. JS (Place before </body>)

<script src="https://cdn.jsdelivr.net/gh/citum/citum-core@main/docs/assets/citum-interactive.js"></script>

auto_fix_high Requirements

Requires HTML output generated by the Citum processor (including v0.6.0+), which includes the semantic classes and data attributes used by the interactive layer.

view_sidebar Sidebar Layout

To enable the sidebar mode on large screens, wrap your content and bibliography in a container with the class citum-with-sidebar.