Colophon

This site is a static documentation hub that pulls its content from ~40 open-source GitHub repositories, enriches it for search engines and AI agents, and deploys on every change. Here is how it fits together.

Architecture at a glance

flowchart TD
    subgraph Sources["GitHub repos (~40)"]
        R1[README.md]
        R2[docs/*.md]
    end

    subgraph Build["Build pipeline"]
        SYNC[sync-docs.mjs<br/>+ repo-config.json]
        ASTRO[Astro + Starlight]
        SEO[astro-seo-graph<br/>JSON-LD + validation]
    end

    subgraph Delivery["Delivery"]
        GH[GitHub Actions]
        PAGES[GitHub Pages]
        CF[Cloudflare edge]
    end

    Sources --> SYNC --> ASTRO --> SEO --> GH --> PAGES --> CF --> User["Browsers & AI agents"]

Framework & tooling

• Astro — static site generator; ships zero JavaScript by default.
• Starlight — Astro’s documentation theme, providing the sidebar, search, and page layout. The site runs dark-mode only with a Primer navy palette.
• astro-mermaid — renders ```mermaid``` code blocks (like the diagram above) with a pinned dark theme.
• Content collections — every page is Markdown under src/content/docs/, validated by a typed content schema.
• Node build scripts — plain ESM modules (scripts/*.mjs), no framework lock-in.

Content pipeline

Almost none of the page content is written here directly. Instead, a sync script fetches it from the source repositories on a schedule and normalizes it for the site.

• scripts/sync-docs.mjs driven by scripts/repo-config.json fetches each repo’s README.md and selected docs/ files.
• Relative image and link URLs are rewritten to work on the site, and an “Edit on GitHub” footer is appended so every page links back to its source.
• Per-page JSON-LD files, the root Markdown mirrors, and the sitemap route list are regenerated, and orphaned files are pruned.
• The Sync Documentation GitHub Action runs daily (and on script changes), commits any differences, and triggers a redeploy.

SEO

• @jdevalk/astro-seo-graph builds a schema.org JSON-LD graph for every page and validates the build: a single <h1> per page, unique titles and descriptions, sensible metadata length, and non-broken internal links.
• A site-wide WebSite + Person graph with a SearchAction is injected in the document head.
• @astrojs/sitemap generates the sitemap, with lastmod derived from each source file’s git history.
• A machine-readable schema graph is served at /schema/docs.json, discoverable via /schemamap.xml and /.well-known/api-catalog.
• Generated Open Graph images give every page a social preview.

AI-friendliness (agent-ready)

The site is built to be readable by AI agents as well as people, and passes the isitagentready.com checks:

• /llms.txt — an llmstxt.org-format overview of the whole site, advertised through a Cloudflare Link: rel="describedby" response header.
• Markdown content negotiation — a Cloudflare Worker returns clean Markdown when a client sends Accept: text/markdown, converting the HTML with Workers AI.
• WebMCP — when a browser exposes navigator.modelContext, the site lazy-loads /webmcp.js to offer tools to on-device agents.
• Agent Skills — the site publishes and documents reusable AI agent skills, exposed for discovery.
• Per-page .jsonld mirrors and flat Markdown copies at the repo root make the content easy to fetch and parse without rendering.

Hosting & delivery

• GitHub Pages hosts the static build, deployed by the Deploy to GitHub Pages Action on every push to main and after each docs sync.
• Cloudflare sits in front of the custom domain soderlind.no, adding response headers (Link, No-Vary-Search), immutable caching for hashed assets, and the Markdown-negotiation Worker.