The Vault - James Burchill

This repository is the source for the public vault at https://vault.jamesburchill.com.

The public homepage is index.md. This README is for operating the repository.

Publishing Model

Content is written as Markdown and published as a static site with Eleventy and GitHub Pages. The Markdown files are the source of record; the generated website is the readable public view.

On every push to main, GitHub Actions builds the site and deploys the generated _site/ output to GitHub Pages.

Source Layout

• index.md controls the public homepage.
• search.md controls /search/, the client-side search page powered by /search-index.json.
• about.md controls /about/.
• now.md controls /now/.
• content/YYYY/MM/*.md contains dated articles, notes, and source material.
• assets/YYYY/MM/ contains images and supporting files for dated content.
• assets/ contains shared site assets such as logos and icons.
• search-index.json.njk, feeds/vault.json.njk, feeds/rss.xml.njk, llms.txt.njk, and sitemap.xml.njk generate machine-readable discovery files.
• 404.md controls the GitHub Pages not-found page.
• redirects.njk generates static redirect pages for imported WordPress URLs using original_url.
• scripts/generate-provenance.mjs writes post-build provenance files into _site/.
• scripts/validate-provenance.mjs checks the generated provenance index, per-article documents, and rendered HTML hashes.

Create Content

Use the Makefile helper:

make content "My New Piece"

It creates:

content/YYYY/MM/my-new-piece.md
assets/YYYY/MM/

To backdate or future-date a piece:

make content "My New Piece" DATE=2026-05-10

To preview what would be created without writing files:

make content-dry-run "My New Piece"

Front Matter

New content should usually include front matter like this:

---
title: "Example Page"
date: 2026-05-10
slug: example-page
summary: "One-sentence summary for search and previews."
topics:
  - publishing
  - markdown
status: published
original_url: ""
featured_image: ""
canonical_url: ""
---

Use original_url for imported legacy URLs. Use featured_image for social previews and article metadata. Leave canonical_url blank unless the canonical URL should deliberately point somewhere other than the generated vault URL.

Machine-Readable Publishing

Markdown files in content/YYYY/MM/ are canonical. JSON, RSS, llms.txt, and sitemap files are generated projections from that Markdown during the Eleventy build.

Generated public artefacts include:

• /search/ for in-site search over published article metadata.
• /search-index.json for lightweight search, AI, and discovery metadata.
• /feeds/vault.json for JSON Feed consumers.
• /feeds/rss.xml for RSS readers.
• /llms.txt for AI-oriented discovery.
• /sitemap.xml for crawler discovery.
• /.well-known/provenance.json for the site-level provenance index.
• /content/YYYY/MM/slug/provenance.jsonld for per-article provenance documents.

The generated JSON is not maintained by hand. Run make build or npm run build locally to validate content metadata and regenerate the public artefacts into _site/. The GitHub Pages workflow runs the same build on every push to main.

Provenance

The build generates machine-readable provenance for every published dated article in content/YYYY/MM/*.md.

The site-level index is published at:

/.well-known/provenance.json

Each article gets a companion JSON-LD document beside the rendered page:

/content/YYYY/MM/slug/provenance.jsonld

The provenance files include the article URL, title, source path, rendered HTML hash, created and modified timestamps, build metadata, and a future signing extension point. The hash uses SHA-256 over the rendered HTML in _site/, not the Markdown source, because the public page is what readers and crawlers actually receive.

Timestamps use UTC ISO-8601. date front matter is used for creation. updated or modified front matter is used for modification when present; otherwise the generator falls back to Git history, then build time if Git metadata is unavailable.

Signing is optional. Local builds without PROVENANCE_SIGNING_PRIVATE_KEY_JWK emit unsigned provenance with an explicit signing.status value. Builds with PROVENANCE_SIGNING_PRIVATE_KEY_JWK emit Ed25519 signatures and publish the matching public key at /.well-known/provenance-key.jwk.

PROVENANCE_SIGNING_PRIVATE_KEY_JWK can contain either a full Ed25519 private JWK JSON object or a 32-byte hex Ed25519 seed. The latter is the output shape from:

openssl rand -hex 32

Signatures cover the RFC 8785-style canonical JSON payload with the top-level signature field omitted. Ed25519 signatures can be verified with a public JWK from PROVENANCE_PUBLIC_KEY_JWK or from the generated site file /.well-known/provenance-key.jwk.

The expected signature shape is:

{
  "signature": {
    "type": "DataIntegrityProof",
    "algorithm": "Ed25519",
    "canonicalization": "RFC8785",
    "key_id": "provenance-ed25519-2026-05",
    "created": "2026-05-12T00:00:00.000Z",
    "value": "base64url-signature"
  }
}

Validate provenance locally after a build:

npm run validate:provenance

To require signatures during validation:

npm run validate:provenance:signatures

Images

Put images for a dated piece in the matching assets folder:

assets/YYYY/MM/image-name.jpg

Reference them from Markdown with an absolute site path:

![Alt text for the image](/assets/YYYY/MM/image-name.jpg)

Site CSS constrains article images to the text width, so large source images can remain large on disk without breaking the page layout.

Local Preview

Install dependencies once:

npm install

Run the local preview server:

make preview

Then open the URL printed by Eleventy, usually http://127.0.0.1:8000 or the next available port.

Build

Run a production build locally:

make build

or:

npm run build

Import WordPress Content

The temporary importer can pull public WordPress posts into the vault format:

make import-wordpress-dry-run
make import-wordpress

Review imported Markdown and images before publishing.

GitHub Pages

In the GitHub repository settings, configure Pages to use GitHub Actions as the build and deployment source.

When the custom domain is ready, set vault.jamesburchill.com in GitHub Pages and point DNS at GitHub Pages.