A template for building structured, version-controlled knowledge bases with an ontology-first approach. Edit a config file, add markdown data, get a full HTML site + JSON API.

Knowledge as Code is a pattern created by Sam Rogers at Snap Synapse. It applies software engineering practices to knowledge management: plain text, Git-native, zero-dependency, ontology-driven, multi-output from a single source.

• AI Capability Reference — AI model capabilities across 12 products
• AI Regulation Tracker — global AI regulatory landscape
• Meeting Standards Reference — meeting facilitation standards

1. Use this template — click "Use this template" on GitHub, or clone locally
2. Edit project.yml — define your domain entities, groups, colors, and site identity
3. Add data — create markdown files in data/ following the schema in data/_schema.md
4. Build — node scripts/build.js
5. Deploy — push to GitHub, Pages deploys automatically

• Static HTML site — homepage, list pages, detail pages, coverage matrix, timeline, comparison tool
• JSON API — programmatic access at docs/api/v1/
• Bridge pages — SEO-targeted pages like "Does X require Y?"
• Dark/light theme — with persistence
• Client-side search — lazy-loaded, keyboard-navigable
• Sortable tables — click any column header to sort
• MCP server — AI agent access to your knowledge base
• Discovery files — llms.txt, agents.json, RSS for machine consumption
• Zero dependencies — Node.js built-ins only

project.yml          # Domain configuration (edit this first)
data/
  examples/          # Example data (replace with your own)
    primary/         # Stable anchor entities (e.g., requirements, obligations)
    container/       # Grouping entities (e.g., frameworks, regulations)
    authority/       # Source entities (e.g., organizations, regulators)
    mapping/         # index.yml connecting containers to primaries
scripts/
  build.js           # Config-driven site generator
  validate.js        # Cross-reference validator
docs/                # Generated output (do not edit)

Every knowledge-as-code project has four entity roles:

Authority → Container → Provision → Primary

Primaries are stable; containers are unstable. When a framework is amended, its provisions change, but the underlying requirements persist.

All domain-specific settings live in project.yml:

• Entity names — what to call each entity type (e.g., "Requirement" vs "Obligation")
• Groups — categories for primary entities, with dark/light mode colors
• Statuses — lifecycle states for containers, with colors
• Navigation — site nav items
• Bridge pages — which SEO pages to generate
• Theme — accent colors

node scripts/build.js      # Build the site
node scripts/validate.js   # Validate cross-references

• File-over-App — data in markdown files, not a database
• Zero dependencies — no npm install, no supply chain risk
• Bespoke static generation — the build script is the specification
• GitOps — Git is the single source of truth

Every Knowledge-as-Code site includes machine-readable discovery files:

• MCP Server — mcp-server.js provides read-only access to all entities via Model Context Protocol. Tools are dynamically named from your project.yml config. Run with node mcp-server.js or add to your MCP client config via mcp.json.
• llms.txt — Generated at docs/llms.txt with entity model, API endpoints, and entity listings for LLM context
• agents.json — Machine-readable metadata at docs/agents.json for agent discovery
• RSS feed — Recent updates at docs/index.xml
• JSON API — Programmatic access at docs/api/v1/

Knowledge as Code includes a verification scaffold for detecting stale data:

• Add last_verified: YYYY-MM-DD to entity frontmatter
• Run node scripts/verify.js to check for staleness
• Configure threshold in project.yml under verification.staleness_days
• See VERIFICATION.md for details on adding AI-assisted verification

Knowledge as Code is part of a broader set of open standards:

• Graceful Boundaries — How services communicate operational limits to humans and agents
• Siteline — AI agent readiness scanner for websites
• Knowledge as Code — The pattern definition and community hub

Knowledge as Code has six defining properties:

1. Plain text canonical — knowledge in human-readable, version-controlled files
2. Self-healing — automated verification detects when knowledge drifts from reality
3. Multi-output — one source produces every format needed (HTML, JSON API, MCP, SEO pages)
4. Zero-dependency — no external packages; nothing breaks when you come back in a year
5. Git-native — Git is the collaboration layer, audit trail, and deployment trigger
6. Ontology-driven — a vendor-neutral taxonomy maps to domain-specific implementations

Read the full pattern definition at knowledge-as-code.com.

Knowledge as Code was created by Sam Rogers / Snap Synapse. See ATTRIBUTION.md for details.

When you use this template, update the following:

1. Edit project.yml with your domain entities, colors, and site identity
2. Replace example data in data/examples/ with your own
3. Update docs/CNAME with your custom domain (or remove it)
4. Push to GitHub — Pages deploys automatically via the included workflow

MIT