> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-server-langgraph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```yaml theme={null}
   ---
   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 `&lt;` in tables and text
   * Escape `>` as `&gt;` in tables and text
   * Escape `&` as `&amp;` 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

```mdx theme={null}
# My Guide

This guide explains...
```

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

**Fix**: Always start with proper frontmatter

```mdx theme={null}
---
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

```mdx theme={null}
See [Authentication](../getting-started/authentication.mdx)
```

**Why**: Mintlify routing doesn't use file extensions

**Fix**: Use path-style links

```mdx theme={null}
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`:

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

***

### ❌ DON'T: Use `<` or `>` Unescaped

```mdx theme={null}
| Deployment Frequency | <1 hour |  ❌ BREAKS
```

**Why**: MDX interprets `<` as start of JSX tag

**Fix**: Use HTML entities

```mdx theme={null}
| Deployment Frequency | &lt;1 hour |  ✅ WORKS
```

***

## Creating New Documentation

### Step 1: Choose the Right Location

```dockerfile theme={null}
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

```bash theme={null}
# 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

```yaml theme={null}
---
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

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

### Step 6: Validate

```bash theme={null}
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)

```mdx theme={null}
✅ [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

```mdx theme={null}
✅ [GitHub Repo](https://github.com/vishnu2kmohan/mcp-server-langgraph)
✅ [Contributing](https://github.com/vishnu2kmohan/mcp-server-langgraph/blob/main/CONTRIBUTING.md)
```

### Anchor Links

```mdx theme={null}
✅ [Jump to Section](#section-heading)
✅ [Prerequisites](/deployment/kubernetes#prerequisites)
```

***

## Icon Selection

See [Icon Selection Guide](/reference/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

```mdx theme={null}
## 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](/reference/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

```bash theme={null}
# 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 `&lt;` and `>` with `&gt;`
* 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](/reference/icon-selection-guide)
* **Mermaid diagrams**: [Mermaid Guide](/reference/mermaid-guide)
* **Templates**: `docs-templates-mintlify/` directory
* **Mintlify docs**: [https://mintlify.com/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.