sphinx-ai-assistant

Sphinx AI Assistant

A Sphinx extension that adds AI-powered features to documentation pages, making it easier to use your documentation with AI tools.

Features

Markdown Export

• Copy as Markdown: Convert any documentation page to Markdown format with a single click
• View as Markdown: Open the markdown version of the current page in a new browser tab
• Perfect for pasting into ChatGPT, Claude, or other AI tools
• Preserves code blocks, headings, links, and formatting
• Clean conversion that removes navigation, headers, and other non-content elements

Integration with AI tools

• Direct AI Chat Links: Open ChatGPT or Claude with pre-filled documentation context
• Smart Content Strategy: Uses pre-generated markdown files for clean, unlimited-length context
• Customizable AI Providers: Built-in support for Claude, ChatGPT, and custom AI services
• No Backend Required: Pure static files, works on any hosting
• MCP (Model Context Protocol) integration: Connect VS Code and Claude to your MCP

Installation

Using pip

pip install sphinx-ai-assistant

Development Installation

git clone https://github.com/mlazag/sphinx-ai-assistant.git
cd sphinx-ai-assistant
pip install -e .

Usage

Basic Setup

• Add the extension to your conf.py:

extensions = [
    # ... your other extensions
    'sphinx_ai_assistant',
]

• Build your documentation:

sphinx-build -b html docs/ docs/_build/html

That's it! The AI Assistant button will now appear on every page:

• Main button: Copy page as Markdown
• Dropdown:
  • Copy or view page as Markdown
  • Ask Claude and ChatGPT
  • Connect to MCP server in VS Code and Claude Desktop

Configuration

For details, see example_conf.py

You can customize the extension in your conf.py:

# Enable or disable the extension (default: True)
ai_assistant_enabled = True

# Button position: 'sidebar' or 'title' (default: 'sidebar')
# 'sidebar': Places button in the right sidebar (above TOC in Furo)
# 'title': Places button near the page title
ai_assistant_position = 'sidebar'

# CSS selector for content to convert (default: 'article')
# For Furo theme, you might want: 'article'
# For other themes, adjust as needed
ai_assistant_content_selector = 'article'

# Enable/disable specific features (default: as shown)
ai_assistant_features = {
    'markdown_export': True,  # Copy to clipboard
    'view_markdown': True,    # View as Markdown in new tab
    'ai_chat': True,          # AI chat links
    'mcp_integration': False, # Not yet implemented
}

# Build-time markdown generation from topics
ai_assistant_generate_markdown = True

# Patterns to exclude from markdown generation
ai_assistant_markdown_exclude_patterns = [
    'genindex',
    'search',
    'py-modindex',
    '_sources',  # Exclude source files
]

# llms.txt generation
ai_assistant_generate_llms_txt = True
ai_assistant_base_url = 'https://docs.example.com'  # Or use html_baseurl

# AI provider configuration
ai_assistant_providers = {
    'claude': {
        'enabled': True,
        'label': 'Ask Claude',
        'description': 'Ask Claude about this topic.',
        'icon': 'anthropic-logo.svg',
        'url_template': 'https://claude.ai/new?q={prompt}',
        'prompt_template': 'Get familiar with the documentation content at {url} so that I can ask questions about it.',
    },
    'chatgpt': {
        'enabled': True,
        'label': 'Ask ChatGPT',
        'description': 'Ask ChatGPT about this topic.',
        'icon': 'chatgpt-logo.svg',
        'url_template': 'https://chatgpt.com/?q={prompt}',
        'prompt_template': 'Get familiar with the documentation content at {url} so that I can ask questions about it.',
    },
    # Example: Custom AI provider
    'custom': {
        'enabled': True,
        'label': 'Ask Perplexity',
        'url_template': 'https://www.perplexity.ai/?q={prompt}',
        'prompt_template': 'Analyze this documentation: {url}',
    },
}

How It Works

Markdown Conversion

When you click "Copy content":

• The extension identifies the main content area of the page
• Removes non-content elements (navigation, headers, footers, etc.)
• Converts the HTML to clean Markdown using Turndown.js
• Copies the result to your clipboard
• Shows a confirmation notification

The converted Markdown includes:

• All text content
• Headings (with proper ATX-style formatting)
• Code blocks (with language syntax highlighting preserved)
• Links and images
• Lists and tables
• Block quotes

AI Chat Integration

When you click "Ask Claude" or "Ask ChatGPT":

With build-time markdown generation (recommended):

• Extension checks if .md file exists for current page
• Opens AI chat with clean URL to markdown file
• AI can fetch unlimited content directly from your server

Without markdown generation (fallback):

• Converts page to markdown using JavaScript
• Embeds markdown in URL query parameter
• Truncates if needed (URL length limits)

Examples

Using with AI Tools

After copying a page as Markdown, you can paste it into:

ChatGPT/Claude:

Here's the documentation for [feature]:

[paste markdown here]

Can you help me understand how to use this?

Cursor/VS Code:

# Context from docs

[paste markdown here]

# Question
How do I implement this in my project?

Development

Project Structure

sphinx-ai-assistant/
├── sphinx_ai_assistant/
│   ├── __init__.py          # Main extension module
│   └── static/
│       ├── ai-assistant.js   # JavaScript functionality
│       ├── ai-assistant.css  # Styling
│       └── *.svg             # Icons
├── pyproject.toml            # Package configuration
└── README.md                 # This file

Building Documentation

cd docs/
sphinx-build -b html . _build/html

Creates:

docs/_build/html/
├── index.html
├── index.md          # Generated markdown
├── tutorial.html
├── tutorial.md       # Generated markdown
└── llms.txt          # List of all markdown pages

Theme Compatibility

Currently optimized for:

• Furo - Full support with sidebar integration
• Alabaster - Supported
• Read the Docs - Supported
• Book Theme - Supported

The extension should work with most themes but may require CSS adjustments.

Troubleshooting

Markdown files not generated

# Install dependencies
pip install beautifulsoup4 markdownify

# Check configuration
grep ai_assistant_generate_markdown conf.py

# Rebuild
sphinx-build -b html docs/ docs/_build/html

AI chat has no content

• Check if .md file exists:

  curl -I https://your-docs.com/page.md
  

• Check browser console for errors

Markdown features not working

This happens when .md file doesn't exist.

Solution: Generate .md files with ai_assistant_generate_markdown = True

Performance

Build Time

• Adds few seconds per 100 pages for markdown generation

Runtime

• With .md files: Instant (just opens URL)
• Without .md files: 100-500ms for first conversion
• Cached for subsequent uses

File Size

• Markdown files are 40-60% smaller than HTML
• Example: 45 KB HTML → 18 KB Markdown

License

MIT License - see LICENSE file for details

Questions or Issues?

• Check the example_conf.py
• Open an issue
• Start a discussion

Acknowledgments

• Built with Turndown.js for HTML to Markdown conversion
• Uses BeautifulSoup4 and markdownify for build-time conversion
• Designed to work seamlessly with the Furo Sphinx theme
• Inspired by the need to make documentation more AI-friendly