mkdocs-gemini-chatbot 1.0.1
A MkDocs plugin to add a Gemini-powered chatbot to your documentation site.
License: MIT
Requires Python: >=3.8

# MkDocs Gemini Chatbot Plugin



[![PyPI version](https://badge.fury.io/py/mkdocs-gemini-chatbot.svg)](https://badge.fury.io/py/mkdocs-gemini-chatbot)

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:**

    ```bash
    pip install mkdocs-gemini-chatbot
    ```

2.  **Get a Gemini API Key:**

    -   Go to [Google AI Studio](https://aistudio.google.com/).
    -   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.

```yaml
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:

```yaml
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.