TextRefs

An open, persistent, machine-readable registry for canonical text references.

Site: https://textrefs.org · Built with Astro + Starlight.

About

TextRefs is a non-profit infrastructure project that builds, maintains, and publishes an open registry for canonical text references — the kind of identifiers used to cite a passage in Plato, a Bekker line in Aristotle, a Stephanus page, or any other established reference system in the humanities. It is being set up as a Zürich-based association (Verein) in formation, which will seek tax-exempt non-profit status.

TextRefs is:

• an open, persistent, machine-readable registry of canonical text references;
• a set of open standards, JSON-LD shapes, and reference implementations;
• a curated source of mappings between canonical references and external identifiers (CTS URNs, Wikidata IDs, DOIs, ARKs, Perseus URLs, etc.).

TextRefs is not:

• a full-text database or a critical edition;
• a publisher or commercial SaaS;
• a substitute for Perseus, Loeb, TLG, PHI, DTS, CTS, or any library catalogue.

Quick links

• Site: https://textrefs.org
• URL layout (what /id/, /reg/, /cite/, /api/ do): https://textrefs.org/get-started/url-layout/
• Standard: https://textrefs.org/standard/
• API documentation: https://textrefs.org/api/
• Association (mission, statutes, governance, expenses): https://textrefs.org/association/
• POSI self-assessment (Principles of Open Scholarly Infrastructure): https://textrefs.org/association/posi/
• Zenodo community (archived data dumps and DOIs): https://zenodo.org/communities/textrefs/
• Statuten (German original, legally binding): https://textrefs.org/de/association/statutes/

Repository structure

.
├── public/                     # static assets (logo, favicon, Inter fonts)
├── src/
│   ├── components/             # Starlight component overrides (Footer)
│   ├── content/docs/           # site content (English at root, German under de/)
│   ├── styles/brand.css        # brand tokens (see public/BRAND notes)
│   └── content.config.ts
├── data/                       # git submodule → textrefs/registry (hand-authored YAML)
├── scripts/                    # data compile + validate pipeline
├── standard/, api/             # scaffolds reserved for future repo splits
├── decisions/                  # Architecture Decision Records (MADR)
├── docs-internal/              # maintainer-only notes, not published
├── astro.config.mjs            # Astro + Starlight config (i18n, sidebar)
├── cliff.toml                  # git-cliff config for CHANGELOG generation
├── commitlint.config.js        # conventional-commit enforcement
└── package.json

Local development

Prerequisites: Node 24 and npm.

Configuration lives in .env; use .env.example as the starting point. SITE_DOMAIN controls Astro's canonical site URL and defaults to textrefs.org when unset.

Command	Action
npm install	Install dependencies; wires git hooks (husky + lint-staged)
npm run dev	Start local dev server at localhost:4321
npm run build	Build the production site to ./dist/
npm run build:fast	Build the site against a tiny fixture registry, without compiling full data
npm run preview	Preview the build locally
npm run compile:data	Read hand-authored YAML under data/works/ and data/systems/, expand the in-memory registry, and emit JSONL resources plus datapackage.json under dist/dump/
npm run validate:data	Validate every compiled record against the canonical Zod schemas
npm run build:data	compile:data then validate:data — the contributor data pipeline
npm run verify:fast	Fast local check using fixture registry data
npm run verify	Prettier + astro check + production build — the CI gate
npm run changelog	Regenerate CHANGELOG.md from git history (git-cliff)

Contributors edit the YAML under data/works/ and data/systems/; the directory is a git submodule pointing at textrefs/registry. Run git submodule update --init --recursive after cloning. The compiler expands the pinned submodule into the flat registry dump (works, systems, refs, mappings) under dist/dump/. See docs/get-started/authoring for the format. For documentation, styling, and route work, use npm run verify:fast locally; run the full npm run verify before PRs that touch registry data, release output, production build behaviour, or CI behaviour.

See AGENTS.md for the full layout and conventions.

Deployment

GitHub Pages deployment is handled by .github/workflows/pages.yml. On pushes to main, the workflow installs dependencies, builds the Astro site, writes dist/CNAME from SITE_DOMAIN, uploads the dist/ artifact, and deploys it with the official GitHub Pages actions.

Set the repository variable SITE_DOMAIN under GitHub Actions variables to the custom domain, for example textrefs.org. If the variable is absent, CI falls back to textrefs.org. The same variable is also read by astro.config.mjs to set Astro's canonical site value.

Citation

If you cite TextRefs, use the metadata in CITATION.cff — GitHub renders a "Cite this repository" button in the sidebar that reads from this file.

Two distinct concept DOIs cover the project, minted via the Zenodo GitHub integration once enabled:

• TextRefs Standard (this repository) — cite for the specification, JSON-LD context, Zod schemas, and site. DOI badge will be added once the first v* tag is released.
• TextRefs Registry (textrefs/registry) — cite for a specific registry data export. DOI badge will be added once the first v* tag is released there.

Both deposits live in the TextRefs Zenodo community.

Support

Topic	Channel
🚨 Bug reports	GitHub Issues
🎁 Feature requests	GitHub Issues
📊 Bad data / mapping corrections	GitHub Issues (label: data)
📚 Docs issues	GitHub Issues
🛡 Security vulnerabilities	See SECURITY.md — private GitHub advisory
🤝 Code-of-Conduct concerns	[email protected]
💬 General questions	GitHub Discussions

Roadmap

TextRefs is pre-1.0: the association is being founded, the standard is being drafted, and the current registry examples are candidate data. Public milestones will appear on the GitHub project board once it is set up. The statutes (English, Deutsch) and governance regulation describe the long-term scope.

Contributing

Contributions are welcome — issues, pull requests, mapping proposals, documentation improvements. Please read CONTRIBUTING.md and the Code of Conduct before opening a PR.

Versioning

This project follows Semantic Versioning. Pre-1.0 releases are considered unstable. The changelog is generated from Conventional Commits via npm run changelog (git-cliff).

Two release trains live in two repositories:

• TextRefs Standard (this repo) — tags vMAJOR.MINOR.PATCH[-prerelease] advance the spec, schemas, and site together. The spec's maturity level (working-draft → candidate-recommendation → recommendation) is encoded in each /standard/* page's frontmatter; the SemVer tag encodes pre-release status.
• TextRefs Registry (textrefs/registry) — calendar tags vYYYY.MM.N cut monthly registry exports. The data-package version inside datapackage.json follows SemVer-without-v.

Records can be re-minted (e.g. when a work key is renamed). The old IRI continues to resolve as a tombstone (status: withdrawn); successors are linked by an exactMatch MappingAssertion. See versioning policy for the full rules.

Contributors and roles

Contributor roles follow the CRediT taxonomy (NISO ANSI/NISO Z39.104-2022). CITATION.cff has no native CRediT field today, so this README is the canonical record.

• Moritz Mähr (@maehr, moritzmaehr.ch) — Conceptualization, Data curation, Funding acquisition, Investigation, Methodology, Project administration, Resources, Software, Supervision, Validation, Visualization, Writing – original draft, Writing – review & editing.
• Luz Christopher Seiberth — Conceptualization, Data curation, Funding acquisition, Writing – review & editing.

See also the GitHub contributors graph.

License

This repository carries three kinds of work under three licences:

• Code — AGPL-3.0-or-later
• Docs & standard text — CC BY-SA 4.0
• Registry data — CC0 1.0

See LICENSE.md for the index and what each licence covers.