# Docs Authoring

> Author and review the WebMCP documentation site using its Diataxis structure, Mintlify conventions, writing rules, design system, and source-of-truth boundaries. Use when creating, editing, reorganizing, or validating pages under apps/documentation-website.

- Skill: `webmcp-org/docs-authoring` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add webmcp-org/docs-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/webmcp-org/docs-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: WebMCP-org (https://skillmd.com/u/webmcp-org)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/webmcp-org/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](../../../AGENTS.md); this file covers the
docs-specific rules (Diataxis, writing style, Mintlify components, source-of-truth
boundaries).

## What this is

Documentation for [WebMCP](https://webmachinelearning.github.io/webmcp/), a Community Group proposal for exposing website tools through `document.modelContext`. Built with
[Mintlify](https://mintlify.com). Live at
[docs.mcp-b.ai](https://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.

| Tab               | Path prefix                      | Diataxis type          |
| ----------------- | -------------------------------- | ---------------------- |
| **Home**          | `index`, `start-here/`           | Landing + routing      |
| **Packages**      | `packages/`, `reference/webmcp/` | Information-oriented   |
| **Tutorials**     | `tutorials/`                     | Learning-oriented      |
| **How-To Guides** | `how-to/`                        | Goal-oriented          |
| **Explanation**   | `explanation/`                   | Understanding-oriented |

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

| File                                   | Purpose                                                                   |
| -------------------------------------- | ------------------------------------------------------------------------- |
| `apps/documentation-website/docs.json` | Navigation, theme, config. **Do not modify without explicit request.**    |
| `../diataxis/SKILL.md`                 | Diataxis framework overview and compass                                   |
| `../diataxis/references/`              | 17 unabridged Diataxis reference pages from diataxis.fr                   |
| `../mintlify/SKILL.md`                 | Mintlify best practices (components, navigation, frontmatter, deployment) |
| `references/design-system.mdx`         | Brand colors, typography, Mintlify component examples                     |

---

## Diataxis framework

This documentation follows [Diataxis](https://diataxis.fr/) 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](/explanation/design/security-and-human-in-the-loop) for details)"
- **How-to** → link to explanation with one sentence of context: "For background on transports, see [Transports and Bridges](/explanation/architecture/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.

| Concept                           | Canonical page                                                    |
| --------------------------------- | ----------------------------------------------------------------- |
| What is WebMCP                    | `explanation/what-is-webmcp`                                      |
| WebMCP vs MCP                     | Chrome's external `compare-mcp` guide                             |
| WebMCP API sources                | `reference/webmcp/standard-api`                                   |
| Declarative API                   | `reference/webmcp/declarative-api`                                |
| Codex site tools compatibility    | `reference/webmcp/codex-site-tools`                               |
| WebMCP and MCP-B extensions       | `explanation/strict-core-vs-mcp-b-extensions`                     |
| Runtime layering / initialization | `explanation/architecture/runtime-layering`                       |
| Transports and bridges            | `explanation/architecture/transports-and-bridges`                 |
| Tool lifecycle                    | `explanation/architecture/tool-lifecycle-and-context-replacement` |
| Security model                    | `explanation/design/security-and-human-in-the-loop`               |
| Schemas and structured output     | `how-to/use-schemas-and-structured-output`                        |
| WebMCP resources and status       | `explanation/design/spec-status-and-limitations`                  |
| Choosing a runtime                | `how-to/choose-runtime` (native vs polyfill vs global)            |
| Package API details               | `packages/<name>/reference`                                       |

---

## 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:

```yaml
---
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:

| Need                                       | Component                                    |
| ------------------------------------------ | -------------------------------------------- |
| Sequential instructions                    | `<Steps>` with `<Step title="...">` children |
| Show code in multiple languages/frameworks | `<CodeGroup>`                                |
| Supplementary info the reader can skip     | `<Note>`                                     |
| Helpful context (permissions, prereqs)     | `<Info>`                                     |
| Best practice or recommendation            | `<Tip>`                                      |
| Potentially destructive or breaking action | `<Warning>`                                  |
| Success confirmation                       | `<Check>`                                    |
| Hide optional details                      | `<Accordion>`                                |
| User chooses one option                    | `<Tabs>` with `<Tab>` children               |
| Linked navigation cards                    | `<Card>` in `<CardGroup>`                    |
| Side-by-side comparison                    | `<Columns>`                                  |
| Diagrams and flowcharts                    | `<Mermaid>`                                  |
| Images with light/dark mode                | `<Frame>`                                    |

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:**

| Topic                      | Canonical URL                                                                                   |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| Community Group draft      | https://webmachinelearning.github.io/webmcp/                                                    |
| WebMCP repository overview | https://github.com/webmachinelearning/webmcp/blob/main/README.md                                |
| Declarative API explainer  | https://github.com/webmachinelearning/webmcp/blob/main/declarative-api-explainer.md             |
| Implementation status      | https://github.com/webmachinelearning/webmcp/blob/main/implementation-status.md                 |
| Security questionnaire     | https://github.com/webmachinelearning/webmcp/blob/main/security-privacy-questionnaire.md        |
| Security and privacy       | https://webmachinelearning.github.io/webmcp/#security-and-privacy-considerations                |
| WPT source and results     | https://github.com/web-platform-tests/wpt/tree/master/webmcp and https://wpt.fyi/results/webmcp |
| Web Platform Status        | https://webstatus.dev/features/document-modelcontext                                            |
| W3C Community Group        | https://www.w3.org/community/webmachinelearning/                                                |
| Model Context Protocol     | https://modelcontextprotocol.io/specification/latest                                            |

**Chrome team developer docs (link to these prominently):**

| Topic                 | URL                                                           |
| --------------------- | ------------------------------------------------------------- |
| WebMCP overview       | https://developer.chrome.com/docs/ai/webmcp                   |
| Imperative API        | https://developer.chrome.com/docs/ai/webmcp/imperative-api    |
| Declarative API       | https://developer.chrome.com/docs/ai/webmcp/declarative-api   |
| Use cases             | https://developer.chrome.com/docs/ai/webmcp/use-cases         |
| Best practices        | https://developer.chrome.com/docs/ai/webmcp/best-practices    |
| Build tools           | https://developer.chrome.com/docs/ai/webmcp/build-tools       |
| WebMCP and MCP        | https://developer.chrome.com/docs/ai/webmcp/compare-mcp       |
| Evaluation            | https://developer.chrome.com/docs/ai/webmcp/evals             |
| Secure tools          | https://developer.chrome.com/docs/ai/webmcp/secure-tools      |
| Chrome DevTools panel | https://developer.chrome.com/docs/devtools/application/webmcp |
| Chrome DevTools MCP   | https://github.com/ChromeDevTools/chrome-devtools-mcp         |

**Chrome-linked experimental tools and demos:**

| Topic                                           | URL                                                                                                 | Local clone                                  |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| Model Context Tool Inspector (Chrome Web Store) | https://chromewebstore.google.com/detail/webmcp-model-context-tool/gbpdfapgefenggkahomfgkhfehlcenpd | -                                            |
| Tool Inspector source                           | https://github.com/beaufortfrancois/model-context-tool-inspector                                    | `webmcp-tools/model-context-tool-inspector/` |
| webmcp-tools repo (demos + utilities)           | https://github.com/GoogleChromeLabs/webmcp-tools                                                    | `webmcp-tools/`                              |
| Live WebMCP explainer                           | https://googlechromelabs.github.io/webmcp-tools/demos/explainer/                                    | `webmcp-tools/demos/explainer/`              |
| Awesome WebMCP list                             | https://github.com/GoogleChromeLabs/webmcp-tools/blob/main/AWESOME_WEBMCP.md                        | `webmcp-tools/AWESOME_WEBMCP.md`             |

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

| Topic                    | URL                                                                                      |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| Codex site tools         | https://learn.chatgpt.com/docs/webmcp                                                    |
| ChatGPT built-in browser | https://learn.chatgpt.com/docs/browser                                                   |
| Site tools Help Center   | https://help.openai.com/en/articles/20001423-using-site-tools-in-the-chatgpt-desktop-app |

**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](https://developer.chrome.com/docs/ai/webmcp/declarative-api) and the Community Group's [declarative explainer](https://github.com/webmachinelearning/webmcp/blob/main/declarative-api-explainer.md). 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](https://googlechromelabs.github.io/webmcp-tools/demos/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](https://webmachinelearning.github.io/webmcp/#security-and-privacy-considerations) and Chrome's [secure tools guidance](https://developer.chrome.com/docs/ai/webmcp/secure-tools) for the full threat model.
- When mentioning native Chrome support, link to the [Model Context Tool Inspector](https://chromewebstore.google.com/detail/webmcp-model-context-tool/gbpdfapgefenggkahomfgkhfehlcenpd) 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:**

| Our page                                | What to keep                                     | What to defer upstream                                                                          |
| --------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `reference/webmcp/standard-api.mdx`     | Upstream source map and MCP-B package boundary   | API tables, signatures, dictionaries, and algorithms → Community Group draft                    |
| `reference/webmcp/declarative-api.mdx`  | Upstream source map and MCP-B coverage links     | Attributes, events, schema synthesis, and browser behavior → Chrome and Community Group sources |
| `reference/webmcp/codex-site-tools.mdx` | Dated compatibility observations and source map  | Availability, setup, product security, and supported features → OpenAI                          |
| `explanation/what-is-webmcp.mdx`        | High-level "what and why", ecosystem positioning | Detailed API walkthrough → link to the Community Group draft                                    |

### What we own (document fully)

| Topic                              | Location                                                                        |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| `@mcp-b/*` package APIs            | `packages/*/README.md` and `packages/*/src/`                                    |
| Package architecture & philosophy  | `AGENTS.md`, `docs/MCPB_PACKAGE_PHILOSOPHY.md`                                  |
| Polyfill behavior & initialization | `packages/webmcp-polyfill/`, `packages/global/`                                 |
| React hooks                        | `packages/react-webmcp/`, `packages/usewebmcp/`                                 |
| Transports, iframe, relay          | `packages/transports/`, `packages/mcp-iframe/`, `packages/webmcp-local-relay/`  |
| Tooling (smart-dom-reader, etc.)   | `packages/smart-dom-reader/`, etc.                                              |
| Type contracts                     | `packages/webmcp-types/src/*.test-d.ts`                                         |
| Chromium flags & testing           | `e2e/web-standards-showcase/CHROMIUM_FLAGS.md`, `e2e/tests/CHROMIUM_TESTING.md` |

---

## Brand

| Key           | Value                                      |
| ------------- | ------------------------------------------ |
| Primary color | #005F8F (see `docs.json` `colors`)         |
| Product name  | "WebMCP" (not "MCP-B" in user-facing docs) |
| Package scope | `@mcp-b/*`                                 |
| Organization  | WebMCP-org                                 |
| Docs URL      | docs.mcp-b.ai                              |
| Live demo     | webmcp.sh                                  |
| Icons         | Font Awesome (see docs.json)               |

---

## 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

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

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