Citations Manager for the Sly.so Blog
- Python 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Balazs Horvath
379b4f30b2
- Fix bibtex.py to skip @String, @Comment, @Preamble entries - Add test_models.py, test_bibtex.py, test_repository.py, test_formatter.py, test_validator.py - Add pytest.ini configuration - Add __init__.py for tests package |
||
| citar | ||
| tests | ||
| .gitignore | ||
| pyproject.toml | ||
| pytest.ini | ||
| README.md | ||
citar — Citations Manager for the Sly.so Blog
Reusable citation/references manager that parses BibTeX files from
~/research/, validates citation links, and generates Pelican-ready
HTML footnotes for blog posts.
Installation
cd ~/src/citar
pip install -e .
Requires requests (already in the environment). No other external deps.
Usage
CLI
# Build a merged citation database from all ~/research/*.bib files
citar build
# Save to a JSON file for inspection
citar build -o ~/.citar/citations.json
# Check all citation URLs are reachable
citar check
# Generate Markdown citations for a post (inline + references section)
citar cite -k arxiv:2607.10183v2,spiritbuun/buun-llama-cpp
# Generate HTML inline citations (for posts with raw HTML)
citar cite -k arxiv:2607.10183v2 -f html
# Search citations by keyword
citar search DSPark
citar search turbo kv
# Health check with full report
citar health
Python API
from citar import build_repository, body_citation, references_section_html
repo = build_repository(["~/research"])
# Inline citations in order
body = repo.format_body_html(["arxiv:2607.10183v2", "spiritbuun/buun-llama-cpp"])
# → '<a href="#ref-1">[1]</a> <a href="#ref-2">[2]</a>'
# References section at the bottom
refs = repo.format_references_html(["arxiv:2607.10183v2", "spiritbuun/buun-llama-cpp"])
# Health check
report = repo.health()
print(report.healthy)
Configuration
Create ~/.citar.toml:
[paths]
bib_dirs = "~/research"
citation_dir = "~/.citar"
validation_timeout = 10
Integration with Pelican Blog
See blog_plugin.py in the repo root — a Pelican custom content processor
that auto-generates footnote HTML in ## References sections.
Alopex Integration
The validator borrows concepts from Alopex's verification pipeline:
- Multi-step validation (HEAD → GET fallback)
- Graceful degradation on timeouts and connection errors
- Clear error categorization (timeout, connection error, too many redirects, HTTP status)
Format
Inline Citations (body)
<a href="#ref-16">[16]</a>
Reference Items (bottom)
<p><a id="ref-16"></a><a href="https://arxiv.org/abs/2607.10183">[16]</a>
Paper: "Automated Tensor Scheduling..." (arXiv:2607.10183)</p>
Data Models
Citation— parsed BibTeX entry with title, author, year, URL, DOIValidationResult— single URL check result (reachable, status code, error)HealthReport— aggregate health check for the full citation set