Docs Authoring

WebMCP Documentation: Authoring Guide

Reference for writing and editing the WebMCP docs. The repo-wide agent instructions live in the root AGENTS.md; this file covers the docs-specific rules (Diataxis, writing style, Mintlify components, source-of-truth boundaries).

What this is

Documentation for WebMCP, a Community Group proposal for exposing website tools through document.modelContext. Built with Mintlify. Live at docs.mcp-b.ai.

Site structure

apps/documentation-website/docs.json is the single source of truth for navigation, pages, groups, and hierarchy. Read it first.

Every package gets an overview page and a reference page under packages/<name>/. The reference/webmcp/ pages route proposal and platform details to upstream sources and sit in the same tab. explanation/design/spec-status-and-limitations keeps its legacy URL but is a reference directory in the WebMCP platforms and agents navigation group.

Key files

Diataxis framework

This documentation follows Diataxis by Daniele Procida. Read ../diataxis/SKILL.md for the full compass. Read ../diataxis/references/<type>.md for the complete reference on each type before writing or editing a page of that type.

The four types (never mix on a single page)

Tutorials (../diataxis/references/tutorials.md):

• A guided learning experience. The teacher holds responsibility. The learner follows.
• Concrete steps, no choices, no branching. Every step produces a visible result.
• Zero conceptual explanation. "We're using HTTPS because it's more secure" is enough. Link to the explanation page for the full story.
• Language: "We will...", "First, do X. Now, do Y.", "Notice that...", "You have built..."

How-to guides (../diataxis/references/how-to-guides.md):

• Directions for a competent user solving a real problem.
• Assumes the reader knows the basics and has a specific goal.
• Can branch ("If you need X, do Y"). Addresses real-world conditions.
• No digression, no explanation, no teaching. "If they're important, link to them."
• Language: conditional imperatives. "To do X, run Y."

Reference (../diataxis/references/reference.md):

• Technical description of the machinery. Austere, factual, structured like the code.
• Consulted while working, not read cover-to-cover.
• Describe and only describe. No teaching, no opinions. Link to how-to guides for usage and explanation pages for the "why".
• Language: "X does Y.", "You must use X.", lists, tables, warnings.

Explanation (../diataxis/references/explanation.md):

• Discursive treatment that deepens understanding.
• Read after stepping away from work. Discusses why, provides context, weighs alternatives.
• Admits opinion and perspective. Makes connections across topics.
• Language: "The reason for X is...", "Consider...", analogies, history, alternatives.

Cross-linking between types

Each type is deliberately incomplete. Links are how the reader moves between them. Every page should have at least 2-3 outgoing links to related pages, woven naturally into prose (not a "See also" dump at the bottom).

• Tutorials → link to explanation pages parenthetically: "(see Security Model for details)"
• How-to → link to explanation with one sentence of context: "For background on transports, see Transports and Bridges." Link to reference pages on first mention of any package.
• Reference → link to how-to for practical usage, explanation for the "why"
• Explanation → link to other explanation pages for related concepts, reference pages when naming specific APIs

Canonical locations for concepts

If a concept is covered on multiple pages, one page owns it. All others link to it.

Writing style

Follow the writing-clearly-and-concisely skill (~/.claude/skills/writing-clearly-and-concisely/SKILL.md). It covers active voice, concision, AI pattern avoidance, and Strunk's composition principles. Read it before writing or editing any page.

WebMCP-specific rules

• Second-person ("you") for instructions
• Lead with the verb in steps: "Install the package", not "You should install the package"
• No em dashes. Use commas, periods, or parentheses.
• No excessive bold. Bold for terms on first definition only.
• No emoji unless the user requests them.

Product names

• "WebMCP" for the proposal and browser API
• @mcp-b/* for packages
• "MCP-B" only in package scope contexts (npm scope, commit messages)
• "Declarative" for the declarative API and its tools; "form" only for the HTML form element

Code examples

• Every example must be real, taken from source code, tests, or package READMEs. Do not invent code.
• Specify language for syntax highlighting
• Add titles to code blocks: "filename.ext"
• Use CodeGroup for multi-framework examples
• Use twoslash for TypeScript/TSX hover type information
• Check document.modelContext before using it (if (!document.modelContext) throw ...) or use optional chaining; webmcp-types declares it optional
• Make long examples (50+ lines) expandable

Mintlify format

Follow the mintlify skill (../mintlify/SKILL.md) for components, navigation patterns, page frontmatter, and deployment. It covers everything from docs.json configuration to component selection to the verification checklist.

The Mintlify MCP server is configured in .mcp.json and available to all agents. Use it to search Mintlify's latest docs instead of relying on training data.

Read references/design-system.mdx for brand-specific component examples (colors, typography, callout usage).

Frontmatter requirements

Every page needs at minimum:

---
title: 'Page Title in Sentence case'
description: 'Concise summary for SEO'
---

Include keywords for discoverability. Include sidebarTitle when the full title is too long for the sidebar. Include icon when the page is a landing or index page.

Links

• Internal links: root-relative, no extension: [text](/path/to/page)
• Paths must match entries in docs.json
• New pages must be added to docs.json navigation

Headings

Use sentence case for all headings and code block titles ("Getting started", not "Getting Started").

Component selection

Pick the right component for the job. See ../mintlify/SKILL.md for the full list. Quick reference:

Rules:

• All code blocks must have a language tag
• Use <Steps> with <Step> children, not <Steps> with ### headings inside
• Do not overuse callouts. One per section at most. If everything is a note, nothing is.
• Do not nest components more than two levels deep

Source of truth: what we own vs. what upstream owns

This is critical. WebMCP is an active Web Machine Learning Community Group proposal, not a W3C Standard or Standards Track document. Our project (@mcp-b/*) provides a polyfill and runtime for that proposed API. The docs must make this distinction clear and always point to the canonical upstream sources for the proposal itself.