Documentation Authoring Guide

Complete guide for contributing to MCP Server LangGraph documentation including Mintlify standards, file formats, and best practices

Documentation Authoring Guide

Last Updated: 2025-11-17 Purpose: Establish clear documentation standards and prevent content drift

---

Documentation Philosophy

Single Source of Truth: Every piece of user-facing documentation should exist in exactly one canonical location.

Discoverability First: If documentation isn’t linked from Mintlify navigation (docs.json), most users will never find it.

---

File Format Policy

✅ USE .mdx for All Documentation in docs/

Location: docs/**/*.mdx (registered in docs/docs.json)

Policy: The docs/ directory is exclusively for Mintlify .mdx files. No .md files allowed.

When to use:

• Getting started guides
• API documentation
• Deployment guides
• Architecture documentation
• Tutorials and examples
• Troubleshooting guides
• Security and compliance docs
• Contributor documentation (this guide!)

Requirements:

1. Frontmatter (required):

   ---
   title: "Page Title"
   sidebarTitle: "Short Title"  # optional, for sidebar
   description: "SEO-friendly description (140-160 chars recommended)"
   icon: "font-awesome-icon-name"  # See Icon Selection Guide
   contentType: "explanation|reference|tutorial|how-to|guide"
   seoTitle: "Page Title - MCP Server LangGraph"  # required (50-60 chars)
   seoDescription: "Expanded description for search engines"  # required (150-160 chars)
   keywords:  # required (5-10 keywords)
     - keyword1
     - keyword2
     - mcp server
     - langgraph
   ---

SEO Field Guidelines:

• seoTitle: Optimized for search engines (50-60 characters), typically {title} - MCP Server LangGraph
• seoDescription: Expanded version of description (150-160 characters) for search engine snippets
• keywords: Array of 5-10 relevant keywords including domain keywords (mcp server, langgraph)

2. Navigation (required):

   • Must be registered in docs/docs.json
   • Place in appropriate tab and group
   • Use logical ordering

3. Links (required):

   • Use Mintlify-style paths: /getting-started/introduction
   • NOT relative paths: ../getting-started/introduction.md
   • NOT file extensions: /getting-started/introduction (not .mdx)

4. Special Characters (required):

   • Escape < as < in tables and text
   • Escape > as > in tables and text
   • Escape & as & if not part of HTML entity

5. File Naming (required):

   • Use lowercase kebab-case: my-guide-name.mdx
   • NOT UPPERCASE: MY_GUIDE_NAME.mdx
   • NOT snake_case: my_guide_name.mdx
   • NOT camelCase: myGuideName.mdx

---

⚠️ .md Files Allowed ONLY Outside docs/

Allowed .md files (outside docs/ directory):

• Root-level files: README.md, CHANGELOG.md, SECURITY.md, CONTRIBUTING.md
• docs-internal/*.md - Internal contributor documentation
• Development notes, research, scratch files

NOT allowed:

• Any .md files in docs/ directory
• User-facing guides in .md format
• Duplicates of .mdx files

---

Directory Structure

docs/
├── getting-started/        # New user onboarding
├── guides/                 # Task-oriented tutorials
├── api-reference/          # API documentation
├── deployment/             # Deployment guides
│   ├── advanced/           # Advanced deployment topics
│   ├── kubernetes/         # Kubernetes-specific guides
│   └── operations/         # Operations and maintenance
│
├── ci-cd/                  # CI/CD documentation
├── architecture/           # Architecture decisions (ADRs)
├── security/               # Security documentation
├── comparisons/            # Framework comparisons
├── advanced/               # Advanced topics
├── reference/              # Reference documentation
│   ├── documentation-authoring-guide.mdx  # This file
│   ├── icon-selection-guide.mdx           # Icon reference
│   ├── mermaid-guide.mdx                  # Diagram standards
│   └── sources.mdx                        # Citations & references
│
└── docs.json               # Mintlify navigation config

---

Common Mistakes to Avoid

❌ DON’T: Create Duplicate Documentation

❌ docs/quickstart.md
❌ docs/getting-started/quickstart.mdx

Why: Creates content drift, confusion about source of truth

Fix: Keep only the .mdx version in the appropriate location

---

❌ DON’T: Forget Frontmatter

# My Guide

This guide explains...

Why: Mintlify won’t render metadata, icons, or SEO correctly

Fix: Always start with proper frontmatter

---
title: "My How-To Guide"
description: 'Brief description'
icon: "book"
contentType: "how-to"
---

# My How-To Guide

This guide explains...

---

❌ DON’T: Use UPPERCASE File Names

❌ docs/deployment/MY_GUIDE.mdx
❌ docs/security/SECURITY_POLICY.mdx

Why: Violates Mintlify best practices, inconsistent URLs

Fix: Use lowercase kebab-case

✅ docs/deployment/my-guide.mdx
✅ docs/security/security-policy.mdx

---

❌ DON’T: Use File Extensions in Links

See [Authentication](../getting-started/authentication.mdx)

Why: Mintlify routing doesn’t use file extensions

Fix: Use path-style links

See [Authentication](/getting-started/authentication)

---

❌ DON’T: Forget to Register in docs.json

Even if the file exists, it won’t be accessible unless it’s in docs.json:

{
  "group": "Getting Started",
  "pages": [
    "getting-started/introduction",
    "getting-started/quickstart"  // ← Must be here!
  ]
}

---

❌ DON’T: Use < or > Unescaped

| Deployment Frequency | <1 hour |  ❌ BREAKS

Why: MDX interprets < as start of JSX tag

Fix: Use HTML entities

| Deployment Frequency | <1 hour |  ✅ WORKS

---

Creating New Documentation

Step 1: Choose the Right Location

User guide? → docs/guides/your-guide.mdx
API docs? → docs/api-reference/your-endpoint.mdx
Deployment? → docs/deployment/your-topic.mdx
Reference? → docs/reference/your-reference.mdx

Step 2: Use a Template

# Copy appropriate template
cp docs-templates-mintlify/guide-template.mdx docs/guides/my-guide.mdx

Available templates (in docs-templates-mintlify/):

• adr-template.mdx - Architecture Decision Records
• guide-template.mdx - How-to guides
• deployment-template.mdx - Deployment guides
• reference-template.mdx - API reference

Step 3: Add Frontmatter

---
title: "Clear, Descriptive Title"
sidebarTitle: "Short Title"  # Optional, for long titles
description: 'What this page helps users accomplish'
icon: "semantic-font-awesome-icon"  # See Icon Selection Guide
contentType: "explanation|reference|tutorial|how-to|guide"
---

Step 4: Write Content

• Start with context: Why does this page exist?
• Use headings: Organize with ##, ###, ####
• Add examples: Code blocks with syntax highlighting
• Link related docs: Help users navigate
• Test locally: Run mintlify dev to preview

Step 5: Register in docs.json

{
  "group": "Your Group",
  "pages": [
    "path/to/existing",
    "path/to/your-new-doc"  // ← Add here (lowercase, no extension)
  ]
}

Step 6: Validate

cd docs

# Check for broken links (PRIMARY validator)
mintlify broken-links

# Preview locally
mintlify dev

---

Migration Policy

When converting .md to .mdx:

1. ✅ Read the original .md file
2. ✅ Add frontmatter with appropriate metadata
3. ✅ Preserve all content exactly as-is
4. ✅ Fix any </> escaping issues in tables
5. ✅ Update internal links to Mintlify format
6. ✅ Use lowercase kebab-case for filename
7. ✅ Register in docs.json at appropriate location
8. ✅ Delete the original .md file
9. ✅ Run validation: mintlify broken-links

---

Link Formatting

Internal Links (Within Docs)

✅ [Getting Started](/getting-started/introduction)
✅ [API Reference](/api-reference/sdk-quickstart)
✅ [Icon Guide](/reference/icon-selection-guide)
❌ [Getting Started](../getting-started/introduction.md)
❌ [Getting Started](./getting-started/introduction.mdx)

External Links

✅ [GitHub Repo](https://github.com/vishnu2kmohan/mcp-server-langgraph)
✅ [Contributing](https://github.com/vishnu2kmohan/mcp-server-langgraph/blob/main/CONTRIBUTING.md)

Anchor Links

✅ [Jump to Section](#section-heading)
✅ [Prerequisites](/deployment/kubernetes#prerequisites)

---

Icon Selection

See Icon Selection Guide for comprehensive icon reference.

Common icons:

• rocket - Getting started, quickstart
• book - Guides, tutorials
• code - API, SDK
• server - Deployment, infrastructure
• shield - Security
• chart-line - Metrics, observability
• infinity - CI/CD
• cloud - Cloud providers
• book-open - Documentation, authoring

---

Content Quality Standards

Writing Style

• Be concise: Respect reader’s time
• Be specific: “Run make test” not “Run tests”
• Be actionable: Focus on “how” more than “what”
• Be consistent: Use same terminology throughout

Code Examples

## Good Example

\`\`\`bash
# Install dependencies
uv sync --extra dev

# Run tests
make test-unit
\`\`\`

## What It Does
This installs development dependencies and runs unit tests.

Screenshots/Diagrams

• Prefer Mermaid for diagrams (see Mermaid Guide)
• Optimize images: Compress before committing
• Add alt text: For accessibility

---

Pre-Commit Checklist

Before committing documentation changes:

• Frontmatter complete and accurate (including contentType)
• File name is lowercase kebab-case
• Added to docs.json navigation
• All < and > escaped in tables
• Internal links use Mintlify format (/path/to/page)
• No duplicate .md version exists
• Ran mintlify broken-links (no errors)
• Tested with mintlify dev (renders correctly)
• Spell-checked and grammar-checked

---

Validation

Pre-commit Hooks

The following validations run automatically:

Pre-commit stage (local):

• Frontmatter quote style check
• File naming conventions (lowercase)
• ADR synchronization

Pre-push stage (local + CI):

• mintlify broken-links - PRIMARY validator
  • Checks: frontmatter, links, navigation, syntax, images
  • Duration: ~8-12 seconds
  • This is the single source of truth for docs validation

Manual Validation

# Run all validations
make docs-validate

# Run Mintlify validator only
make docs-validate-mintlify

# Validate frontmatter
python scripts/validators/frontmatter_validator.py --docs-dir docs

# Fix MDX syntax errors
python scripts/fix_mdx_syntax.py --all

---

Troubleshooting

”Syntax error - Unable to parse”

Cause: Unescaped < or > characters, or code blocks missing language tags

Fix:

• Replace < with < and > with >
• Add language tags to code blocks: ```python instead of ```

”Page not found” in Mintlify

Cause: Not registered in docs.json

Fix: Add page path to appropriate group in docs.json

”Broken link” warning

Cause: Link uses wrong format or points to non-existent page

Fix:

• Use /path/to/page format (no extension)
• Verify target page exists and is in docs.json

”Could not parse import/exports with acorn”

Cause: Code block containing import statement doesn’t have language tag

Fix: Add python, javascript, or appropriate language tag to code block

---

Maintenance

Weekly

• Review new documentation PRs for compliance
• Check mintlify broken-links output

Monthly

• Audit for orphaned .md files (should be ZERO in docs/)
• Review docs.json for logical organization
• Update this guide as patterns emerge

---

Getting Help

• Icon reference: Icon Selection Guide
• Mermaid diagrams: Mermaid Guide
• Templates: docs-templates-mintlify/ directory
• Mintlify docs: https://mintlify.com/docs
• Questions?: Open issue with label documentation

---

Remember: All user-facing documentation belongs in .mdx files registered in docs.json. The docs/ directory is exclusively for Mintlify .mdx files - no exceptions.