WEBSITE.md Spec

WEBSITE.md is a root-level Markdown file that gives AI agents durable instructions for operating a website. Simple at the door, deep by design.

Required file

The only required root instruction file is WEBSITE.md. Companion files such as AGENTS.md, DESIGN.md, COPY.md, SEO.md, and media.json are optional.

AGENTS.md tells agents how to work in your repo. WEBSITE.md tells agents how to operate your website.

Core sections (~5 minutes)

• Site Identity
• Primary User Goals
• Site Structure
• Canonical URLs
• Content Sources
• Editing Rules
• Preview And Validation
• Publishing

Conformance levels

Level 0 — Declared: root WEBSITE.md exists
Level 1 — Checked: npx website-md check passes
Level 2 — Addressable: data-wmd-* source mappings in output
Level 3 — Operable: edit operations, page regions, front matter, media
Level 4 — Optimizable: analytics and experiment contracts

Page regions

Optional — recommended for block-based or source-addressable sites

Markdown files contain content blocks. Page JSON arranges those blocks into regions. Regions are layout containers, not content.

Built-in region ids: hero, body, and footer. Identity content belongs in blocks such as blocks/profile.md placed inside the hero region — not in a block named hero.

{
  "version": 1,
  "regions": [
    { "id": "hero", "label": "Hero", "blocks": ["blocks/profile.md"] },
    { "id": "body", "label": "Body", "blocks": ["blocks/links.md"] },
    { "id": "footer", "label": "Footer", "blocks": ["blocks/footer.md"] }
  ]
}

Simple sites can ignore regions. Region ids give themes and renderers stable styling targets.

Optional advanced capabilities

• Source addressability (data-wmd-source, data-wmd-region)
• Page regions (pages/*.json)
• Content capabilities and block front matter (wmd_*)
• Media references and media.json
• Analytics contracts
• A/B testing and experiments (future-facing)
• Agent operations and import/export helpers

Validate

npx website-md check

The full draft lives in the repo as SPEC.md. Beginners can adopt with only the core sections; advanced tools can rely on the same public standard.