# RefKit

> Parse, cite, and tidy bibliographies.

One Rust core. Python and TypeScript APIs for bibliography parsing, citation rendering, and source-preserving BibTeX edits.

## Table of Contents

### Overview

- [RefKit](https://peter-gy.github.io/refkit/index.md): Parse, render, inspect, format, and edit bibliography data from Python, JavaScript, and Polars.

### Start

- [Get Started](https://peter-gy.github.io/refkit/get-started.md): Install RefKit in Python or TypeScript and render the same citation and bibliography.
- [Why RefKit](https://peter-gy.github.io/refkit/why-refkit.md): Understand why RefKit separates normalized bibliography data, raw BibTeX, and styled output.
- [Performance](https://peter-gy.github.io/refkit/performance.md): Measure RefKit capabilities with fixed inputs, correctness checks, isolated workers, and reproducible baseline comparisons.

### Concepts

- [How RefKit Works](https://peter-gy.github.io/refkit/concepts/how-refkit-works.md): Follow RefKit's normalize, render, and raw-edit flows through their state owners.
- [Choose a Bibliography Model](https://peter-gy.github.io/refkit/concepts/bibliography-models.md): Choose Library for normalized behavior or BibDocument for source-preserving BibTeX edits.
- [Citation Rendering](https://peter-gy.github.io/refkit/concepts/citation-rendering.md): Build an ordered citation document and inspect its citations, bibliography, HTML, text, or render tree.
- [Parsing and Recovery](https://peter-gy.github.io/refkit/concepts/parsing-and-recovery.md): Choose exact normalized parsing, report recovery, raw failed blocks, or Polars row diagnostics.

### Guides

- [Parse Bibliographies](https://peter-gy.github.io/refkit/guides/parse-bibliographies.md): Parse bibliography text, inspect normalized entries, project records, and select entries by structure in Python or TypeScript.
- [Render Citations](https://peter-gy.github.io/refkit/guides/render-citations.md): Render named citations and cited or full bibliographies with bundled or explicit CSL styles in Python or TypeScript.
- [Render Structured Output](https://peter-gy.github.io/refkit/guides/render-output.md): Read rendered nodes in a custom consumer while preserving bibliography labels, layout, and source identity.
- [Edit Raw BibTeX](https://peter-gy.github.io/refkit/guides/edit-bibtex.md): Inspect raw BibTeX blocks and duplicate occurrences, then edit field values while preserving source layout in Python or TypeScript.
- [Format BibTeX](https://peter-gy.github.io/refkit/guides/format-bibtex.md): Format BibTeX strings, raw documents, or files and inspect warnings and key renames in Python or TypeScript.
- [Process Polars Columns](https://peter-gy.github.io/refkit/guides/polars.md): Parse, inspect, render, format, broadcast, and diagnose bibliography source inside Polars queries.
- [Run in a Browser](https://peter-gy.github.io/refkit/guides/browser.md): Initialize RefKit in a browser or worker and serve the WebAssembly asset with the required security policy.
- [Run in Pyodide](https://peter-gy.github.io/refkit/pyodide.md): Install RefKit PyEmscripten wheels in the tested Pyodide and Polars runtime set.
- [Troubleshooting](https://peter-gy.github.io/refkit/troubleshooting.md): Diagnose parsing, raw ambiguity, rendering, browser initialization, Polars plugin, source-build, and Pyodide failures.

### Reference

- [Python API](https://peter-gy.github.io/refkit/reference/python.md): Look up every public refkit object, function, result, helper, and runtime metadata contract.
- [TypeScript API](https://peter-gy.github.io/refkit/reference/javascript.md): Look up refkit-js initialization, bibliography objects, rendering, raw edits, formatting, and Node file helpers.
- [Data Shapes](https://peter-gy.github.io/refkit/reference/data-shapes.md): Inspect typed diagnostics, projections, rendered trees, bibliography layout, raw blocks, and Polars reports.
- [Tidy Options](https://peter-gy.github.io/refkit/reference/tidy-options.md): Look up every TidyOptions argument, default, merge strategy, duplicate rule, and key-template behavior.
- [Polars Expressions](https://peter-gy.github.io/refkit/reference/polars.md): Look up bibliography expressions, output formats, dtypes, broadcasting, and row reports.
- [Selectors](https://peter-gy.github.io/refkit/reference/selectors.md): Filter normalized Library entries by type, fields, alternatives, and parent structure.
- [Rust Core](https://peter-gy.github.io/refkit/reference/rust.md): Inspect the source-workspace Rust API that supplies RefKit's portable bibliography capabilities.
- [Use RefKit with Agents](https://peter-gy.github.io/refkit/reference/agent-docs.md): Discover installed RefKit tasks, execute version-matched examples, and retrieve focused agent documentation.
- [Errors and Diagnostics](https://peter-gy.github.io/refkit/reference/errors.md): Distinguish exceptions, parser diagnostics, tidy warnings, and Polars row or query failures.