Athena MCP Docusaurus Documentation Guide

Overview

This guide explains how to use Claude with the Athena MCP Docusaurus tools to manage and contribute to documentation. These tools allow you to search, read, edit, and create documentation directly through Claude, with all changes going through a pull request review process.

Quick Start

New to the documentation tools? Start by checking your permissions and then try finding existing documentation before creating new content.

Table of Contents

1. Getting Started
2. Core Workflows
3. Tool Reference
4. Best Practices
5. Troubleshooting

Getting Started

Prerequisites

• Access to Claude Desktop or Claude.ai
• Athena MCP connection configured
• Appropriate permissions for documentation tools

Checking Your Permissions

Before starting, verify you have access to the documentation tools:

Permission Check

Ask Claude: "Check my permissions for documentation tools"

You should see a list of available tools. If you're missing permissions, contact your administrator.

Core Workflows

1. Finding and Reading Documentation

Search for Documentation

To find documentation on a specific topic:

"Search for documentation about authentication in Aeon"

Claude will use docusaurus_search to find relevant documents and show you:

• Document titles
• File paths
• Content previews
• Relevance scores

Search Tips

• Use specific keywords for better results
• Try different variations if initial search doesn't find what you need
• Search is semantic, so you can describe what you're looking for naturally

Read a Specific Document

Once you've found a document, read its full content:

"Read the file api/authentication.md"

Claude will show you:

• The document's frontmatter (title, description, tags)
• Full markdown content
• File SHA (version identifier)

Browse Documentation Structure

To understand the documentation organization:

"Show me the documentation structure"

Or for a specific section:

"List the structure of the guides folder"

2. Updating Existing Documentation

Important

All documentation changes go through a pull request review process. Never worry about making mistakes - everything is reviewed before going live!

Simple Text Updates

For minor corrections or updates:

"In the authentication guide, update the OAuth section to mention the new token expiration time of 24 hours"

Claude will:

1. Read the current file
2. Stage your changes
3. Show you the change ID
4. Prepare for PR creation

Multiple Updates to One File

For several changes to the same document:

"Update the API reference to:
1. Add a new endpoint for user preferences
2. Update the rate limits section  
3. Fix the typo in the authentication example"

Complex Multi-File Updates

For changes spanning multiple files:

"Update all references to 'API key' to 'API token' across the authentication documentation"

Claude will:

1. Search for all occurrences
2. Stage changes for each file
3. Track all change IDs
4. Prepare a comprehensive PR

3. Creating New Documentation

Create a Single Document

To add new documentation:

"Create a new guide about configuring request rate limits in Aeon. Include sections on:
- Default limits
- Customizing limits
- Monitoring usage
- Troubleshooting"

Claude will:

1. Suggest an appropriate location
2. Create proper Docusaurus frontmatter
3. Format the content with headers
4. Stage the new file

Document Placement

Not sure where to put new documentation? Claude can suggest the best location based on content analysis and existing structure.

Create a Documentation Section

To create a new folder with multiple documents:

"Create a new troubleshooting section with guides for:
- Common errors
- Performance issues
- Integration problems"

Claude will:

1. Create the folder structure
2. Add _category_.json for Docusaurus
3. Create index and individual files
4. Stage all changes

Validate Before Creating

For important documents, validate first:

"Validate this document before creating:
Title: Advanced Configuration Guide
Content: [your content]
Location: guides/advanced-config.md"

4. Submitting Changes for Review

Create a Pull Request

After staging changes:

"Create a pull request with all my staged changes"

Or for specific changes:

"Create a PR with just the authentication updates"

Claude will:

1. Create a feature branch
2. Commit your changes
3. Push to GitHub
4. Create the PR with a summary
5. Provide the PR URL

PR Best Practices

Good PR Titles:

• "Update authentication docs for v2.0"
• "Add troubleshooting guide for common errors"
• "Fix typos in API reference"

Good PR Descriptions:

• List what you changed and why
• Mention any breaking changes
• Reference related issues or tickets

PR Best Practices

Provide context for your PR:

"Create a PR titled 'Update authentication docs for v2.0' with description:
- Updated OAuth flow documentation
- Added new token expiration details
- Fixed code examples"

5. Advanced Workflows

AI-Powered Document Placement

When unsure where to place new content:

"Where should I put a new guide about webhook configuration?"

Claude will analyze the structure and suggest appropriate locations.

Bulk Documentation Updates

For systematic updates:

"Update all API documentation to include rate limit information in a consistent format"

Documentation Migration

To reorganize content:

"Move all troubleshooting guides from the FAQ section to a new dedicated troubleshooting folder"

Tool Reference

Search and Discovery Tools

Tool	Purpose	Example Usage
docusaurus_search	Find documentation by keyword	"Search for API rate limits"
docusaurus_list_structure	Browse folder organization	"Show me the guides structure"
docusaurus_suggest_location	Get AI suggestions for document placement	"Where should I put webhook docs?"

Reading and Validation Tools

Tool	Purpose	Example Usage
docusaurus_read_file	Read complete documents	"Read the OAuth guide"
docusaurus_validate_doc	Validate before creating	"Validate this new guide"
docusaurus_check_permissions	Verify your access	"Check my permissions"

Writing and Creation Tools

Tool	Purpose	Example Usage
docusaurus_stage_changes	Stage edits to existing files	"Update the auth section"
docusaurus_create_doc	Create new documents	"Create a troubleshooting guide"
docusaurus_create_folder	Create folder structures	"Create a new API section"

Publishing Tools

Tool	Purpose	Example Usage
docusaurus_create_pr	Submit changes for review	"Create PR for these updates"

Best Practices

1. Document Structure

Docusaurus Requirements

All documents need proper frontmatter including:

• title: Clear, descriptive title
• description: SEO-friendly description
• sidebar_position: (optional) Numerical position in sidebar
• tags: Relevant keywords for discoverability

Good Document Structure:

---
title: "Setting Up OAuth Authentication"
description: "Complete guide to configuring OAuth authentication in Aeon"
sidebar_position: 2
tags:
  - authentication
  - oauth
  - setup
---

# Setting Up OAuth Authentication

## Overview
Brief introduction to what this guide covers...

## Prerequisites
What users need before starting...

## Step-by-Step Instructions
Detailed implementation steps...

## Troubleshooting
Common issues and solutions...

2. Content Guidelines

Writing Guidelines

• Start with an overview - Tell readers what they'll learn
• Use descriptive headers - Make content scannable with ##, ###
• Include code examples - Show, don't just tell
• Add cross-references - Link to related documentation
• Test your examples - Ensure all code snippets work

3. Workflow Tips

• Always search first - Avoid duplicating existing content
• Stage related changes together - Group logical updates
• Write clear PR descriptions - Help reviewers understand your changes
• Validate complex documents - Use validation tool for important guides

4. Common Patterns

Adding a How-To Guide

"Create a how-to guide for setting up SSO with Okta, place it in the authentication section"

Updating Code Examples

"Update all Python code examples in the API docs to use the new client library v3.0"

Creating Release Notes

"Create release notes for version 2.5 highlighting the new features and breaking changes"

Troubleshooting

Common Issues

File Already Exists

Error: "File already exists"

Solution: Use docusaurus_read_file and docusaurus_stage_changes instead of creating new, or choose a different filename.

No Pending Changes

Error: "No pending changes found"

Solution:

• Ensure you've staged changes before creating a PR
• Check if changes were already submitted in a previous PR

Rate Limit

Error: "Rate limit reached"

Solution:

• Wait a moment before retrying
• Batch operations when possible
• Space out multiple requests

Getting Help

If you encounter issues:

1. Check permissions first - Verify you have access to needed tools
2. Verify file paths - Ensure paths are correct and files exist
3. Check Docusaurus formatting - Validate frontmatter and markdown syntax
4. Contact support - Include the full error message

Examples

Example 1: Fix a Typo

User: "Fix the typo 'authentification' in the OAuth guide"
Claude: [Reads file, stages correction, provides change ID]
User: "Create a PR for this fix"
Claude: [Creates PR with the typo fix]

Example 2: Add New Feature Documentation

User: "Create documentation for the new batch processing API endpoint"
Claude: [Suggests location, creates comprehensive guide, stages it]
User: "Also update the API reference to include this endpoint"
Claude: [Updates reference, stages changes]
User: "Create a PR with both changes"
Claude: [Creates PR with new guide and updated reference]

Example 3: Reorganize Documentation

User: "List all troubleshooting content"
Claude: [Shows scattered troubleshooting docs]
User: "Create a dedicated troubleshooting section and move all these guides there"
Claude: [Creates folder, moves files, updates links, stages everything]
User: "Create a PR titled 'Reorganize troubleshooting documentation'"
Claude: [Creates comprehensive PR]

Sidebar Organization and Ordering

Understanding how Docusaurus organizes documentation in the sidebar helps you place content logically and maintain a good user experience.

How Sidebar Ordering Works

Docusaurus uses position numbers and alphabetical sorting to organize content:

1. Folders with position numbers appear first (lowest to highest)
2. Folders without positions appear next (alphabetical by label)
3. Documents follow the same pattern using sidebar_position in frontmatter

How Sidebar Ordering Works

Docusaurus uses a hierarchical system to determine the order of folders and documents in the sidebar:

Folder Ordering

Folders are ordered using _category_.json files placed in each directory. This file controls:

With Position Numbers:

{
  "label": "Custom Folder Name",
  "position": 25,
  "description": "Folder description for generated indexes"
}

Without Position Numbers (Alphabetical):

{
  "label": "Custom Folder Name", 
  "description": "Folder description for generated indexes"
}

Ordering Rules:

1. Folders with position numbers appear first, sorted by position (lowest to highest)
2. Folders without position numbers appear after, sorted alphabetically by label
3. If no _category_.json exists, the folder uses its directory name and sorts alphabetically

Document Ordering

Individual documents are ordered using the sidebar_position field in their frontmatter:

---
title: "Document Title"
sidebar_position: 3
---

Documents follow the same rules as folders - positioned items first, then alphabetical.

Managing Sidebar Order with Claude

Finding Current Positions

"Show me the documentation structure for the main product folder"

Updating Folder Positions

"Update the authentication folder to appear earlier in the sidebar by changing its position to 5"

Creating New Folders with Proper Positioning

"Create a new troubleshooting section and place it near the end of the main topics"

Claude will suggest an appropriate position based on the existing structure.

Removing Position Numbers

To let a folder sort alphabetically with others:

"Remove the position number from the Claude folder so it sorts alphabetically"

This is useful when you want consistent alphabetical ordering across most folders.

Best Practices for Sidebar Organization

Position Number Strategies

Position Number Strategy

Use sparse numbering (10, 20, 30) to leave room for future additions:

• Position 10: Getting Started
• Position 20: Core Features
• Position 30: Advanced Topics
• Position 40: Administration

Option 1: Sparse Numbering Use positions like 10, 20, 30 to leave room for future additions:

• Position 10: Getting Started
• Position 20: Core Features
• Position 30: Advanced Topics
• Position 40: Administration

Option 2: Alphabetical with Exceptions Let most folders sort alphabetically, but use positions for:

• Critical "getting started" content (position 1-5)
• Important sections that should appear early
• Deprecated content that should appear last (high position numbers)

Folder Naming

• Use clear, descriptive labels in _category_.json
• Consider how names will sort alphabetically
• Avoid technical jargon in folder names visible to end users
• Use consistent naming patterns across similar sections

When to Use Positions vs. Alphabetical

Use Position Numbers When:	Use Alphabetical When:
Content has logical learning progression	Topics are reference material of equal importance
Some topics are more important	Content can be accessed in any order
You want to guide users through specific flow	You want predictable, consistent organization

Common Sidebar Issues and Solutions

"Folder appears in wrong place"

Check if it has a _category_.json file with a position number. Folders with positions always appear before alphabetical folders.

"Want to move folder without affecting others"

If most folders are alphabetical, remove the position from the folder you want to move, and rename it to sort where you want it alphabetically.

"New folder appears at top unexpectedly"

This usually means you created it with a position number while other folders don't have positions. Either add positions to other folders or remove the position from the new one.

"Inconsistent ordering"

Check which folders have _category_.json files and positions. For consistent ordering, either use positions for all folders or none.

Example Workflow: Reorganizing Documentation

User: "The API documentation is appearing too early in the sidebar. I want it after all the basic setup topics."

Claude: "I'll check the current API folder position and move it later in the sequence."
[Reads current _category_.json]
[Updates position from 15 to 35]
[Stages the change]

User: "Perfect, now create a PR with this change."

Claude: [Creates PR with clear description of the positioning change]

This systematic approach to sidebar organization ensures your documentation remains navigable and logical as it grows.

Conclusion

The Athena MCP Docusaurus tools make documentation management efficient and collaborative. By following these workflows, you can contribute high-quality documentation while maintaining consistency and going through proper review processes.

Remember

All changes go through pull request review, so don't worry about making mistakes. Focus on creating clear, helpful documentation that serves your users well!

---

Need more help? Contact the documentation team or check the troubleshooting section for common issues and solutions.