Mintlify documentation

Documentation structure overview

The WebMCP documentation uses a flat + organized directory structure:

Root-level pages

Core documentation pages live in the repository root:

Introduction & Getting Started: introduction.mdx, quickstart.mdx, development.mdx
Core Guides: best-practices.mdx, security.mdx, troubleshooting.mdx, advanced.mdx
Use Cases: building-mcp-ui-apps.mdx, connecting-agents.mdx, frontend-tools.mdx
Examples & Reference: examples.mdx, live-tool-examples.mdx, changelog.mdx

Organized directories

Specialized content is organized into directories:

/concepts/: Core concepts (architecture, tool design, schemas, security, performance, glossary)
/packages/: NPM package reference (react-webmcp, transports, smart-dom-reader, etc.)
/ai-frameworks/: AI framework integrations (assistant-ui, ag-ui, custom runtime)
/extension/: Browser extension documentation (agents, userscripts)
/tools/: Tools documentation (claude-code integration)
/snippets/: Reusable code snippets organized by category (core, templates, validation, imports, patterns, clients)

Key files & directories

docs.json: Mintlify configuration, navigation structure, theme settings, and global metadata
*.mdx: Documentation pages with frontmatter (title, description, sidebarTitle, icon)
/snippets/: Reusable content fragments used across multiple pages (see USING_SNIPPETS.md)
- Organized into subdirectories: core/, templates/, validation/, imports/, patterns/, clients/
/logo/: Brand assets (mcp-b-logo.png)
/.github/: GitHub workflows and automation documentation

The site navigation (defined in docs.json) groups pages conceptually, which may differ from the file structure:

Navigation groups like “Getting Started”, “Guides”, “SDK Reference” are organizational concepts
These groups pull from various locations (root pages and directories)
Always check docs.json to understand the published navigation structure

Contributing to the docs

Before you start

Search existing content: Check if similar information already exists to avoid duplication
Understand the audience: Documentation targets developers working with MCP in browsers
Review existing patterns: Look at similar pages to maintain consistency

Making changes

Start small: Make the smallest reasonable change that solves the problem
Test thoroughly: Verify all code examples work before publishing
Check links: Ensure all internal links use relative paths and are valid
Preview locally: Use mintlify dev to preview changes before committing

Common workflows

Adding a new page: Create MDX file with proper frontmatter → Add to docs.json navigation → Test locally
Updating SDK documentation: Update MDX content → Test code examples → Verify TypeScript types are accurate
Fixing broken links: Use relative paths like ./page-name or ../section/page-name
Adding code examples: Check for existing snippet → If none exists, follow Code Blocks Style Guide → Test the code → Consider creating snippet if used 3+ times
Using reusable snippets: Search /snippets/ directory → Import snippet → Use with props → Preview locally to verify rendering

Working relationship

You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
ALWAYS ask for clarification rather than making assumptions
NEVER lie, guess, or make up information

Project context

Format: MDX files with YAML frontmatter
Config: docs.json for navigation, theme, settings
Components: Mintlify components
Organization: WebMCP-org GitHub organization
Main repository: https://github.com/WebMCP-org/docs

Content strategy

Document just enough for user success - not too much, not too little
Prioritize accuracy and usability of information
Make content evergreen when possible
Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
Check existing patterns for consistency
Start by making the smallest reasonable changes

Reusable snippets

Use snippets from /snippets/ directory for common code patterns
See USING_SNIPPETS.md for complete usage guide with examples
33 snippets available covering all common WebMCP patterns
If a code pattern appears 3+ times, consider creating a snippet
When to use snippets:
- Tool registration patterns (registerTool, useWebMCP)
- Response formats (success, error, markdown)
- Import statements (React, vanilla JS, client)
- Validation schemas (Zod, JSON Schema)
- Client setup (McpClientProvider, transports)
When NOT to use snippets:
- Page-specific examples that benefit from inline context
- One-off code examples (appears only 1-2 times)
- Tutorial walkthroughs where step-by-step explanation is key

docs.json

Refer to the Mintlify configuration schema when building the docs.json file and site navigation
Navigation structure is defined in the “navigation” array
Each group has a “group” name and “pages” array

Frontmatter requirements for pages

title: Clear, descriptive page title
description: Concise summary for SEO/navigation
sidebarTitle: (optional) Shorter title for sidebar display
icon: (optional) Icon name from Font Awesome or Lucide

Writing standards

Second-person voice (“you”)
Prerequisites at start of procedural content
Test all code examples before publishing
Match style and formatting of existing pages
Include both basic and advanced use cases
Alt text on all images
Relative paths for internal links

Code blocks

Follow the Code Blocks Style Guide for all code formatting. Key requirements:

Always specify language for syntax highlighting (e.g., typescript, bash, tsx)
Use twoslash for TypeScript/TSX examples to enable hover type information
Add titles to major code examples (3+ uses or complex): "filename.ext" or "Description"
Use icons to provide visual context (e.g., icon="react", icon="server", icon="npm")
Use lines for reference documentation and tutorial content
Make long examples expandable (50+ lines): add expandable option
Use diff syntax for good vs. bad comparisons: // [!code ++] and // [!code --]
Highlight key lines in teaching examples: highlight={5-12}

Example:

```tsx "MyComponent.tsx" twoslash lines icon="react" highlight={5-7}
import { useWebMCP } from '@mcp-b/react-webmcp';

function MyComponent() {
  useWebMCP({
    name: 'my_tool',
    handler: async (args) => { ... }
  });
}
```

Git workflow

NEVER use —no-verify when committing
Ask how to handle uncommitted changes before starting
Create a new branch when no clear branch exists for changes
Commit frequently throughout development
NEVER skip or disable pre-commit hooks
Use descriptive commit messages following conventional commits

WebMCP-specific guidelines

Reference the official WebMCP-org repositories
Examples repository: https://github.com/WebMCP-org/examples
NPM packages: @mcp-b/transports and related packages
Focus on Model Context Protocol (MCP) functionality
Include TypeScript examples with proper type definitions
Document both browser and Node.js usage patterns

Do not

Skip frontmatter on any MDX file
Use absolute URLs for internal links
Include untested code examples
Make assumptions - always ask for clarification
Reference outdated MiguelsPizza organization links
Commit node_modules or build artifacts

Mintlify documentation reference

Use these official Mintlify resources when working on documentation:

Essential references

Global settings: Complete docs.json configuration options
Navigation: Structure and customize navigation hierarchy
Pages: Page creation and frontmatter requirements
Format text: Text formatting, headers, and styling
Format code: Inline code and code blocks with syntax highlighting

Components

Callouts: Info, warning, success, and error callouts
Cards: Highlight main points with customizable layouts
Tabs: Toggle between different content views
Code groups: Display multiple code examples
Accordions: Collapsible content sections
Steps: Sequential procedural content

Content creation

Reusable snippets: Keep content in sync across pages
Images and embeds: Add images, videos, and iframes
Lists and tables: Display structured information
Redirects and broken links: Prevent invalid links

Best practices

Style and tone: Writing effective technical documentation
Content types: Create the right content for your users
Organize navigation: Information architecture guidelines
Git concepts: Git fundamentals for docs-as-code
Working with branches: Make changes without affecting live docs
SEO: Improve documentation discoverability

Deployment and tools

GitHub integration: Sync docs with GitHub repo
Preview deployments: Preview changes before merging
CLI installation: Preview and maintain docs locally

Getting Started

Guides

NPM Packages

Reference

CLAUDE

Mintlify documentation

Documentation structure overview

Root-level pages

Organized directories

Key files & directories

Navigation organization

Contributing to the docs

Before you start

Making changes

Common workflows

Working relationship

Project context

Content strategy

Reusable snippets

docs.json

Frontmatter requirements for pages

Writing standards

Code blocks

Git workflow

WebMCP-specific guidelines

Do not

Mintlify documentation reference

Essential references

Components

Content creation

Best practices

Deployment and tools

Getting Started

Guides

NPM Packages

Reference

​Mintlify documentation

​Documentation structure overview

​Root-level pages

​Organized directories

​Key files & directories

​Navigation organization

​Contributing to the docs

​Before you start

​Making changes

​Common workflows

​Working relationship

​Project context

​Content strategy

​Reusable snippets

​docs.json

​Frontmatter requirements for pages

​Writing standards

​Code blocks

​Git workflow

​WebMCP-specific guidelines

​Do not

​Mintlify documentation reference

​Essential references

​Components

​Content creation

​Best practices

​Deployment and tools

Mintlify documentation

Documentation structure overview

Root-level pages

Organized directories

Key files & directories

Navigation organization

Contributing to the docs

Before you start

Making changes

Common workflows

Working relationship

Project context

Content strategy

Reusable snippets

docs.json

Frontmatter requirements for pages

Writing standards

Code blocks

Git workflow

WebMCP-specific guidelines

Do not

Mintlify documentation reference

Essential references

Components

Content creation

Best practices

Deployment and tools