How RefKit Works

RefKit moves bibliography data through three flows. Python and JavaScript expose the same state owners and results.

Normalize

Bibliography source becomes a Library of normalized entries and parser diagnostics.

Render

A Library, style, locale, and ordered citations become named citations plus a bibliography.

Edit

A raw BibDocument and an atomic patch become a new snapshot with byte changes and occurrence mappings.

Normalize bibliography input

Library is the normalized citation database. It accepts BibTeX or BibLaTeX, text formats for bibliography entries, and Hayagriva YAML, a structured bibliography format. Each entry exposes a citation key, entry type, common fields, and normalized parent records.

Normalization resolves bibliography syntax into records suited to selection, projection, and rendering. Library.diagnostics records messages from recoverable BibTeX parsing. Python and Node.js also provide file-reading APIs. Browsers supply source text to the same in-memory parsing operations.

Preserve raw BibTeX

BibDocument scans the original source into ordered blocks. An occurrence is one entry or field at one source position. Occurrence identity keeps duplicate entry keys and duplicate field names individually addressable.

apply_patch / applyPatch returns a new snapshot after validating structural edits and reference rewrites. Original entry and field handles retain their values and spans. The result maps old occurrences to new ones and records byte changes. Write the result document through the host's filesystem or browser download API when the workflow needs a file.

Render an ordered citation document

Style prepares a Citation Style Language (CSL) style, a format that describes citation and bibliography rules. Locale validates and stores a bundled locale code. The renderer loads that locale's terms when a Document operation starts.

Document.render accepts ordered, named Citation objects. A CitationGroup holds one or more Cite items. The order can affect disambiguation and the cited bibliography.

Library + Style + Locale + ordered Citation values
                    ↓
                 Document
                    ↓
     named citations + cited bibliography

Each output is Rendered. It exposes the same result as plain text, escaped HTML, and a structured render tree. Each render operation owns fresh citation state. Python and JavaScript reclaim object resources automatically when the objects become unreachable.

Adapt the core to a host

The refkit-core Rust library owns parsing, recovery, raw syntax, formatting, styles, and rendering. Adapters translate those capabilities into host-native values:

Host	Adapter owns
Python	Paths, Python objects, exceptions, native module registration, and one-call helpers.
JavaScript	Typed objects, WebAssembly initialization for the compiled core, and Node.js file helpers.
Polars, a DataFrame query engine	Expressions, broadcasting, column data types, plugin loading, and row failure mapping.
Pyodide, Python running in a browser	The refkit Python API packaged as a wheel for its WebAssembly runtime.

Continue with Choose a Bibliography Model to choose between normalized data and raw source.