MkDocs Gemini Chatbot Plugin

An MkDocs plugin that adds a conversational chatbot to your documentation site, powered by Google's Gemini models. The chatbot uses the entire content of your documentation, including auto-generated API references, to provide intelligent, context-aware answers with precise, clickable links to the relevant sections.

• Conversational AI: Uses Google's Gemini models to understand and answer user questions.
• Full-Site Context: Indexes the content of your entire MkDocs site, including pages generated by other plugins like mkdocstrings.
• Precision Linking: Automatically creates clickable links to the exact section or page being referenced in its answers.
• Responsive Design: A clean, modern UI that works beautifully on both desktop and mobile, with a fullscreen mode for immersive conversations.
• Light & Dark Mode: Automatically adapts its theme to your MkDocs Material theme's color palette.
• Code-Friendly: Renders Markdown responses, with syntax highlighting and a "Copy" button for code blocks.
• Persistent History: Remembers your conversation history within a browser session.
• Secure API Key Handling: Loads your Gemini API key securely from a .env file, so you never have to commit it to your repository.

Installation

1. Install the plugin from PyPI:

   pip install mkdocs-gemini-chatbot
   

2. Get a Gemini API Key:

   • Go to Google AI Studio.
   • Click on "Get API key" and create a new key.

3. Set up your environment:

   • Create a file named .env in the root of your MkDocs project (where your mkdocs.yml file is).

   • Add your API key to the .env file:

     GEMINI_API_KEY="your-secret-api-key-here"
     

   • Important: Add the .env file to your .gitignore to keep your key secure.

Configuration

In your mkdocs.yml file, add gemini-chatbot to your plugins list. No further configuration is needed if you are using a .env file.

site_name: My Awesome Docs

plugins:
  - search
  - mkdocstrings
  - gemini-chatbot # That's it!

Advanced Configuration

You can customize the chatbot's behavior by adding options under the plugin entry:

plugins:
  - gemini-chatbot:
      # Optional: Override the .env file (not recommended)
      # gemini_api_key: "your-key-here"

      # Optional: Change the Gemini model used
      model: "gemini-1.5-pro"

      # Optional: Customize the chat window title
      chat_title: "Ask our AI Assistant"

      # Optional: Set a custom initial greeting
      initial_prompt: "I'm an AI assistant for these docs. How can I help?"

How It Works

The plugin works by hooking into the MkDocs build process.

1. During the build, it processes the final rendered HTML of every page.
2. It intelligently extracts all text content and finds all linkable anchors (e.g., #section-name) created by MkDocs and mkdocstrings.
3. This content and anchor information is saved to a content.json file in your built site directory.
4. When a user asks a question, the chatbot sends the user's query, the conversation history, and the entire site's context to the Gemini API, with specific instructions to use the anchors for precision linking.

This ensures that the AI has the most complete and accurate context to answer questions about your documentation.