National Reusable Code Library

A static site catalogue for NHS healthcare data code. The site indexes GitHub repositories, public and private, using structured YAML metadata, making reusable NHS code discoverable, shareable, and easier to adapt across organisations.

Each entry is assessed against a four-tier reusability framework (Baseline, Bronze, Silver, Gold), carries a 0-100 metadata quality score, and is tagged by category, language, and platform.

Quick start

Requires uv.

uv sync
uv run python scripts/build_catalog.py   # YAML -> catalog.json + generated pages
uv run zensical serve                    # starts at http://localhost:8000

Re-run build_catalog.py after changing anything under library/ or the templates in src/nrcl/templates/.

How it fits together

library/<slug>/metadata.yaml      one YAML file per entry (the submission contract)
        |
        v  scripts/build_catalog.py
docs/js/catalog.json              consumed client-side by the catalogue page
docs/catalog/<slug>/index.md      generated entry detail pages
docs/index.md                     generated home page (stats, featured, stories)
docs/organisations/               generated per-organisation pages
        |
        v  uv run zensical build
site/                             static site, deployed to GitHub Pages

• Schema: src/nrcl/models.py (Pydantic). Field reference: docs/reference/data_model.md
• Quality score: src/nrcl/quality.py, criteria-based, 0-100, shown on every entry with a breakdown of points met and missed
• GitHub enrichment: src/nrcl/github.py fetches stars, last push, and licence for public repos at build time (cached; set NRCL_NO_GITHUB=1 to skip)
• Front end: Zensical (the successor to Material for MkDocs) with NHS branding (docs/css/nhs.css) and vanilla JS for filtering and search (docs/js/), with Fuse.js fuzzy matching
• Demo mode: extra.demo in mkdocs.yml is one switch. While it is on, the site shows a demo bar on every page, entry pages carry a synthetic-example notice, and the weekly link checker skips the synthetic URLs. Turn it off when the library holds real entries
• CI: .github/workflows/validate.yml checks entries, lint, and tests on PRs and on pushes to main; deploy.yml lints, tests, builds, and deploys to GitHub Pages on push to main; submission.yml turns submission issues into pull requests; link_check.yml checks entry links weekly

Adding an entry

Open a submission issue and automation drafts the pull request for you, or add library/<slug>/metadata.yaml yourself (the submit page on the site has a starter file). Validation runs automatically on the PR.

All current entries are synthetic examples for prototyping. No entry may contain patient data, credentials, or anything unsuitable for public listing.

Tests

uv run pytest                      # Python unit tests (models, loader, builder, quality)
node tests/js/catalog_smoke.js     # headless catalogue filter/search test (build first)
uv run ruff check . && uv run ruff format --check .

Deployment

One-time setup: create a GitHub repository, push main, and set Settings -> Pages -> Source to Deploy from a branch, branch gh-pages, root /. Every push to main then validates, builds, and redeploys automatically.

Licence

Code is released under the MIT licence. Documentation and site content are (c) Crown copyright (NHS) and available under the Open Government Licence v3.0, except where otherwise stated.

Project documents

• CLAUDE.md: full project brief
• NEXT_STEPS.md: what is left to do