mkdocs-ask-ai 1.1.0

MkDocs plugin for LLM-friendly documentation with direct markdown serving and i18n support

mkdocs-ask-ai

Make your MkDocs documentation AI-ready. One plugin gives your site everything AI tools need to work with your docs — a "Use with AI" menu for visitors, llms.txt for crawlers, an MCP server for agents, and raw markdown URLs for everything else.

Works with Material for MkDocs and mkdocs-static-i18n out of the box.

---

Features

"Use with AI" Dropdown

A floating button on every page with:

• Copy page as Markdown — one-click clipboard copy for any AI tool
• View as Markdown — opens the clean .md source in a new tab
• Open in ChatGPT — sends page content directly to ChatGPT via ?q= parameter
• Open in Claude — sends page content directly to Claude via ?q= parameter
• llms.txt — link to the full documentation index

Adapts to light and dark themes automatically. Inspired by 1Password's developer docs.

llms.txt + llms-full.txt

Follows the llms.txt standard to make your documentation discoverable by AI systems:

• llms.txt — structured index with sections, titles, and links to markdown sources
• llms-full.txt — complete documentation in a single file for full-context queries

Direct Markdown Serving

Every page is accessible as clean markdown at its .md URL. No HTML parsing needed — AI tools get exactly what they need.

https://your-site.com/getting-started/index.md

MCP Server

Expose your documentation as an MCP server so AI agents can query it programmatically.

Tools:

Tool	Description
list_pages(locale?)	Discover available pages grouped by section
get_page(path, locale?)	Fetch a specific page as markdown
search_docs(query, locale?)	Full-text search with snippets
get_full_docs(locale?)	Get the entire documentation as one text

Transports:

Use case	Transport	Example
Local / private	stdio	Add to Claude Desktop, Cursor, Windsurf
Public website	Streamable HTTP	https://your-site.com/mcp

Every page is also registered as an MCP resource (docs://site-name/path/to/page.md).

i18n Support

Full support for multilingual sites via mkdocs-static-i18n. Each locale gets its own:

• llms.txt and llms-full.txt
• Markdown files at locale-prefixed URLs
• MCP server tools with locale parameter
• docs-index.json with all locales merged

---

Installation

pip install mkdocs-ask-ai

With MCP server support:

pip install mkdocs-ask-ai[mcp]

Quick Start

Add to your mkdocs.yml:

plugins:
  - ask-ai:
      sections:
        "Getting Started":
          - index.md: "Introduction"
          - quickstart.md: "Quick start guide"
        "API Reference":
          - api/*.md

That's it. Your site now has:

• llms.txt and llms-full.txt at the site root
• .md URLs for every page
• "Use with AI" dropdown on every page

Configuration

Basic Options

plugins:
  - ask-ai:
      sections: {}                      # Section names mapped to file patterns (glob supported)
      markdown_description: ""          # Description included in llms.txt header
      enable_ai_menu: true              # Show "Use with AI" dropdown
      ai_menu_button_text: "Use with AI"
      enable_chatgpt: true              # Show "Open in ChatGPT" item
      enable_claude: true               # Show "Open in Claude" item
      enable_markdown_urls: true        # Serve .md files alongside HTML
      enable_llms_txt: true             # Generate llms.txt
      enable_llms_full: true            # Generate llms-full.txt

MCP Server Options

plugins:
  - ask-ai:
      enable_mcp: true                  # Generate docs-index.json for MCP
      mcp_transport: "stdio"            # "stdio" or "streamable-http"
      mcp_path: "/mcp"                  # URL path for streamable HTTP
      mcp_port: 8808                    # Port for standalone HTTP server

Section Patterns

Sections support explicit paths, descriptions, and glob patterns:

sections:
  "Infrastructure":
    - infrastructure/index.md: "Infrastructure overview"
    - infrastructure/proxmox.md: "Proxmox hypervisor"
    - infrastructure/*.md              # glob — include all .md files
  "API":
    - api/*.md

Using the MCP Server

With Claude Desktop / Cursor

Build your site first, then add to your MCP config:

{
  "mcpServers": {
    "my-docs": {
      "command": "mkdocs-ask-ai",
      "args": ["mcp", "--site-dir", "/path/to/public"]
    }
  }
}

Standalone HTTP Server

mkdocs-ask-ai mcp --transport http --port 8808 --site-dir ./public

CLI Reference

mkdocs-ask-ai mcp [OPTIONS]

Options:
  --site-dir PATH          Built site directory (default: ./public)
  --transport {stdio,http} Transport type (default: stdio)
  --port PORT              HTTP port (default: 8808)
  --host HOST              HTTP host (default: 127.0.0.1)

With mkdocs-static-i18n

Place ask-ai before i18n in the plugins list:

plugins:
  - ask-ai:
      sections:
        "Docs":
          - "*.md"
  - i18n:
      docs_structure: suffix
      languages:
        - locale: en
          default: true
          name: English
        - locale: ru
          name: Russian

Output per locale:

public/
  llms.txt              # English
  llms-full.txt
  docs-index.json       # merged index (all locales)
  ru/
    llms.txt            # Russian
    llms-full.txt

License

MIT — see LICENSE.