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)

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
• 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.

What the Community Group and Chrome own (link to these, don't re-document)

Community Group draft and protocol sources:

Chrome team developer docs (link to these prominently):

Chrome-linked experimental tools and demos:

OpenAI product documentation (link to these, don't re-document):

Rules for proposal vs. package content:

• When documenting document.modelContext API shape (methods, parameters, return types), link to the Community Group draft. Describe navigator.modelContext only as a deprecated compatibility alias. Our reference pages should route readers to the authoritative source and identify package-specific differences. Do not maintain a competing API table or full spec.
• When documenting the declarative API (toolname, form attributes, schema synthesis, CSS pseudo-classes, SubmitEvent extensions), link to Chrome's declarative API documentation and the Community Group's declarative explainer. Identify the subset implemented by MCP-B, then link. Do not re-document the full type mapping table, constraint mapping table, or event contract; those will go stale as Chrome iterates.
• When documenting @mcp-b/* packages, document the implemented package behavior fully and link to source. Do not call the package's current type surface the complete WebMCP draft surface. The proposal changes quickly: as of August 2026 it includes executeTool() with object input, while Chrome and MCP-B compatibility implementations accept serialized JSON. Link to the live draft for the proposal and describe the package signature separately. Do not describe unregisterTool, provideContext, or clearContext as current WebMCP methods. BrowserMcpServer adds registerPrompt, registerResource, listTools, and the composed mcpServer property. Protocol-version-specific elicitation and deprecated sampling remain official MCP SDK capabilities accessed through BrowserMcpServer.mcpServer; never describe them as document.modelContext methods.
• When showing the proposal working, prefer the Chrome team's live explainer or an individual demo from GoogleChromeLabs/webmcp-tools rather than recreating it.
• Security model documentation should summarize our approach but link to the draft's security and privacy considerations and Chrome's secure tools guidance for the full threat model.
• When mentioning native Chrome support, link to the Model Context Tool Inspector extension recommended by Chrome's WebMCP documentation. Do not describe it as an officially supported Google product.
• When documenting Codex site tools, link to OpenAI for availability, setup, security, and current limitations. Keep our page dated and limited to independently observed compatibility differences. Do not treat those observations as permanent product behavior or generalize them to Chrome, Codex CLI, or the Codex IDE extension.

Page-specific guidance:

What we own (document fully)

Brand

Do not

• Skip frontmatter (title and description are required on every .mdx file)
• Use absolute URLs for internal links (use root-relative: /path/to/page)
• Use title case for headings (use sentence case: "Getting started", not "Getting Started")
• Write code blocks without a language tag
• Use <Steps> with ### headings inside (use <Step title="..."> children)
• Include untested or invented code examples
• Use placeholder values like "foo" or "bar" in code (use realistic values)
• Reference outdated MiguelsPizza organization links
• Mix Diataxis content types within a single page
• Re-explain a concept that has a canonical page (link to it instead)
• Re-document the proposed WebMCP API surface in detail when the upstream draft is more authoritative. Summarize, then link.
• Blur the line between the WebMCP proposal and MCP-B extensions. Always clarify which layer a feature belongs to.
• Overuse callouts. One per section at most.
• Use decorative formatting, emoji, or excessive bold

Development

pnpm dev:docs # from the repo root. Preview at http://localhost:3000

Deployed automatically on push to main via Mintlify's GitHub integration.