A static portfolio generated from public YAML documents and governed by portable JSON Schemas. Work, teaching, writing and appearances share a controlled taxonomy and a validated index projection.
Requires Python 3.12+ and Node.js 22.12+. Install from the checked-in dependency versions:
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
npm ci
pipx install pre-commit==4.5.1If pre-commit is already installed, reuse it. Select the repository's checked-in hook explicitly:
git config core.hooksPath .githooksThis is a local Git setting, not something cloning installs automatically. CI runs required checks independently of local hooks. A normal build also runs all declared pre-commit checks. Initial tool installation requires network access.
Use Conventional Commits:
fix(links): validate local destinations
The commit-msg hook runs pinned commitlint with the conventional configuration. CI checks incoming commit ranges independently. Breaking source-format changes use ! and a BREAKING CHANGE: footer. Keep messages concise and technical.
Validate a draft without committing:
npm run lint:commits -- --edit path/to/message.txt./buildThe build selects .venv/bin/python when available; PYTHON may select another prepared interpreter. It validates sources first, generates pages and index, rebuilds pinned Pagefind output, runs declared checks, validates final links/anchors/index membership, and runs tests. Invalid input stops the command; it is never skipped.
For read-only validation or tests using the prepared environment:
.venv/bin/python tools/validate_site.py --sources-only
.venv/bin/python tools/validate_site.py
.venv/bin/python -m unittest discover -s tests -t .The first command is the pre-generation phase. The second additionally requires existing generated output. Neither modifies source files. Generated HTML is committed; pagefind/ and dist/ are build-only artifacts. Do not edit generated files manually.
config.yaml: site metadata and navigation.data/TAGS.yaml: stable concept IDs, display labels, facets, search terms and relationships.data/*.yaml: content, referencing concept IDs.schemas/*.schema.json: authoritative JSON Schema Draft 2020-12 documents.tools/contracts.py: YAML parsing, schema enforcement and cross-record rules.tools/model.py: validated rendering adapters.templates/: shared page layout and page templates.tools/build_*.py: generators called in dependency order by./build.tests/: invalid-input, preservation and output checks.
See contract rules, the accepted standards decision and future roadmap, and contributor instructions.
Replace public data and site configuration, choose a namespace for your concepts, and adapt schema $id URIs before publishing your own schema authority. Preserve concept identities separately from labels and HTML anchors. Follow validation errors rather than adding exceptions. Private resume drafts and employment data are not required to build the site.
SKOS export, ODCS integration and OWL translation are recorded future work, not implemented features. The current site does not verify the factual truth of prose claims merely because their document structure validates.
Numerical provenance is planned separately.
CI runs the build and refuses stale committed HTML and rules documentation. The local build does not publish. CI checks search integrity through its build manifest. See development and release for PR protection and gated Pages deployment.
JSON Schemas in schemas/ are the source of the Pydantic models in tools/generated/. ./build regenerates those models before any page imports them. The existing contract check runs datamodel-codegen --check, and CI rejects a build that changes committed generated models. Do not edit generated models by hand. tools/model.py contains loaders and derived presentation helpers. JSON Schema validation remains authoritative for constraints not represented by the generator, including unique items and dependent fields. Dates and URIs remain strings for rendering; JSON Schema validates their formats.