bxc (Bibliographic Reference Formatter)

A lightweight Python library and Command Line Interface (CLI) tool designed to format BibTeX bibliography records into academic styles (like IEEE, ABNT, ACM) using Citation Style Language (CSL). It natively outputs to Markdown, HTML, and Plain Text, making it perfect for static blogs, documentation websites, and automated citation pipelines.

Key Features

• Zero-Configuration UX: Automatically resolves, downloads, and caches standard academic styles (e.g., ieee, nature, abnt) on demand from the official CSL repositories.
• Offline-First Style Resolution: Ships with a bundled, compressed snapshot of the entire CSL styles repository (10,000+ styles, ~1.4MB). Style lookups check this local archive before ever touching the network, so bxc format works instantly and fully offline for any standard style - the CDN is only used for brand-new styles not yet in the bundle, or when explicitly syncing (bxc cache update / bxc cache rebuild).
• LaTeX to Unicode Normalization: Seamlessly cleans and converts LaTeX accent escape codes (like {\e}, \c{c}) to standard Unicode (e.g., è, ç`) prior to formatting.
• Multiple Output Targets: Renders styled reference lists natively to Markdown, HTML, and Plain Text.
• Local Cross-Platform Caching: Caches downloaded styles locally according to OS-native standards (~/.cache/bxc/ on Linux, ~/Library/Caches/bxc/ on macOS, %LOCALAPPDATA%\\bxc\\Cache on Windows; run bxc cache status to see yours).
• Flexible Interface: Use it as a terminal CLI tool or import it as a standard Python library.

Installation

Requires Python 3.12 or newer.

pip / pipx (any platform):

pipx install bxc      # or: pip install bxc

Native installers are attached to each release on the project page, with a SHA256SUMS file to verify them:

The deb and rpm bundle bxc's pure-Python dependencies and use your distribution's python3 and python3-lxml; the package manager installs them for you. They need Python 3.12+, so older distributions (Debian 12, Ubuntu 22.04, RHEL 9) should use pipx instead. The Windows installer is self-contained (it ships its own Python) and adds bxc to the system PATH; it is not code-signed, so Windows SmartScreen may warn on first run. Open a new terminal after installing.

Quick Start

Command Line Interface (CLI)

Format a .bib file to Markdown using IEEE style:

bxc format citations.bib --style ieee --output markdown

Search for a citation style:

bxc search "ABNT"

Clear, sync, or inspect the local cache:

bxc cache update   # refresh the style search index from the CDN
bxc cache rebuild   # re-download every cached style from the CDN (sync with CDN)
bxc cache status   # show cache location and stats
bxc cache clear    # remove all cached styles and the index

bxc cache update and bxc cache rebuild are the commands that talk to the CDN on purpose - they're how you get styles fresher than the bundled snapshot. Everyday bxc format calls never need them: they resolve styles from the bundled local archive first (see Offline-First Style Resolution above), which is why bxc works out of the box without a network connection.

Maintainers can refresh that bundled archive itself (a periodic task, not something end users run) with:

python build_styles_bundle.py

Python API

import bxc

# Parses, converts LaTeX escapes, fetches CSL, and formats citation
markdown_ref = bxc.format_bibtex(
    bibtex_source="@article{smith2026, ...}",
    style="ieee",
    output_format="markdown"
)

print(markdown_ref)

CLI reference

bxc format [BIB] --style STYLE [--output plain|markdown|html] [--mode bibliography|citation] [--cite KEYS] [--out-file PATH]

• BIB (or --bib/-b): path to a .bib file; use - to read from stdin.
• --style/-s: a CSL style name (e.g. ieee, apa) or the path to a local .csl file.
• --cite/-c: comma-separated citation keys to format.
• Exit codes: 0 success, 1 error (parse failure, style not found, ...), 2 invalid usage, 130 interrupted.

bxc search [QUERY] [--category CATEGORY] searches the style registry; bxc cache {status,update,rebuild,clear} manages the local cache.

License

Apache License 2.0. The bundled CSL styles are from the Citation Style Language styles repository and are licensed under CC BY-SA 3.0; see NOTICE.