mkdocs-ai-summary-wcowin 1.0.4

AI-powered summary generation plugin for MkDocs Material

MkDocs AI Summary Plugin

An intelligent MkDocs plugin that automatically generates AI-powered summaries for your documentation pages using multiple AI services including OpenAI, DeepSeek, Google Gemini, and GLM.

Features

• 🤖 Multiple AI Services: Support for OpenAI, DeepSeek, Google Gemini, and GLM
• 🚀 Smart Caching: Intelligent caching system to reduce API calls and costs
• 🎯 Flexible Configuration: Fine-grained control over which pages get summaries
• 🌍 Multi-language Support: Generate summaries in different languages
• 🔧 CI/CD Ready: Seamless integration with GitHub Actions and other CI/CD systems
• 📱 Responsive Design: Beautiful summary cards that work on all devices
• ⚡ Performance Optimized: Minimal impact on build times with smart caching

Installation

From PyPI (Recommended)

pip install mkdocs-ai-summary-wcowin

From Source

git clone https://github.com/Wcowin/Mkdocs-AI-Summary-Plus.git
cd Mkdocs-AI-Summary-Plus
pip install -e .

Quick Start

1. Configure your MkDocs

Add the plugin to your mkdocs.yml:

plugins:
  - ai-summary:
      ai_service: "deepseek"  # or "openai", "gemini", "glm"
      summary_language: "en"  # or "zh"
      cache_enabled: true
      cache_expire_days: 30
      enabled_folders:
        - "docs"
      exclude_patterns:
        - "**/api/**"
        - "**/reference/**"

2. Set up Environment Variables

Create a .env file in your project root:

# Choose one or more AI services
DEEPSEEK_API_KEY=your_deepseek_api_key
OPENAI_API_KEY=your_openai_api_key
GEMINI_API_KEY=your_gemini_api_key
GLM_API_KEY=your_glm_api_key

3. Build Your Documentation

mkdocs build

The plugin will automatically generate AI summaries for your pages and inject them into the content.

Configuration Guide

Local Development Setup

Step 1: Get API Keys

Obtain API keys for your chosen AI service:

DeepSeek (Recommended)

1. Visit DeepSeek Platform
2. Register and log in
3. Go to API management
4. Create a new API key
5. Copy the key for later use

OpenAI

1. Visit OpenAI Platform
2. Log in to your account
3. Go to API Keys page
4. Click "Create new secret key"
5. Copy the key for later use

Google Gemini

1. Visit Google AI Studio
2. Log in with your Google account
3. Create a new API key
4. Copy the key for later use

GLM (Zhipu AI)

1. Visit Zhipu AI Platform
2. Register and log in
3. Go to API management
4. Create an API key
5. Copy the key for later use

Step 2: Create .env File

Create a .env file in your project root (same level as mkdocs.yml):

# In your project root directory
touch .env

Step 3: Configure API Keys

Edit the .env file and add your API keys:

# DeepSeek API Key (Recommended)
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# OpenAI API Key
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Google Gemini API Key
GEMINI_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# GLM API Key
GLM_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxx

# Optional: Debug mode
AI_SUMMARY_DEBUG=false

# Optional: API timeout (seconds)
AI_SUMMARY_TIMEOUT=30

# Optional: Maximum retry attempts
AI_SUMMARY_MAX_RETRIES=3

Important Notes:

• Only configure API keys for the services you plan to use
• Ensure .env file is added to .gitignore to prevent API key leakage
• API key formats vary by service, ensure you copy the complete key

Step 4: Verify Configuration

Run the following commands to verify your configuration:

# Local build test
mkdocs build

# Local preview
mkdocs serve

If configured correctly, you should see the plugin load successfully and generate AI summaries.

GitHub Deployment Configuration

Step 1: Prepare GitHub Repository

1. Push your project to a GitHub repository
2. Ensure .env file is added to .gitignore
3. Ensure mkdocs.yml and plugin configuration are committed

Step 2: Configure Repository Secrets

Configure API keys in your GitHub repository:

1. Access Repository Settings

   • Open your GitHub repository
   • Click the "Settings" tab
   • Find "Secrets and variables" in the left menu
   • Click "Actions"

2. Add Repository Secrets

   Click "New repository secret" and add the following secrets:

   Secret Name	Value	Description
   DEEPSEEK_API_KEY	Your DeepSeek API key	If using DeepSeek service
   OPENAI_API_KEY	Your OpenAI API key	If using OpenAI service
   GEMINI_API_KEY	Your Gemini API key	If using Gemini service
   GLM_API_KEY	Your GLM API key	If using GLM service

   Adding Steps:

   • Name: Enter the secret name (e.g., DEEPSEEK_API_KEY)
   • Secret: Paste your API key
   • Click "Add secret"

Step 3: Create GitHub Actions Workflow

Create .github/workflows/deploy.yml in your repository:

name: Deploy MkDocs with AI Summary

on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4
      with:
        fetch-depth: 0
    
    - name: Setup Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.x'
    
    - name: Cache pip dependencies
      uses: actions/cache@v3
      with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
        restore-keys: |
          ${{ runner.os }}-pip-
    
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install mkdocs-material
        pip install mkdocs-ai-summary-wcowin
        # If you have requirements.txt
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
    
    - name: Build documentation with AI summaries
      env:
        # Configure API key environment variables
        DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        GLM_API_KEY: ${{ secrets.GLM_API_KEY }}
        # Optional configuration
        AI_SUMMARY_DEBUG: false
        AI_SUMMARY_TIMEOUT: 30
      run: |
        mkdocs build --verbose
    
    - name: Deploy to GitHub Pages
      if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./site
        # Optional: Custom domain
        # cname: your-domain.com

Step 4: Enable GitHub Pages

1. In repository settings, find "Pages" option
2. Source: select "Deploy from a branch"
3. Branch: select "gh-pages"
4. Click "Save"

Step 5: Trigger Deployment

Push code to main branch to trigger automatic deployment:

git add .
git commit -m "Add AI summary plugin configuration"
git push origin main

Advanced CI/CD Configuration

Multi-Environment Configuration

name: Deploy Documentation

on:
  push:
    branches: [ main, develop ]
  workflow_dispatch:

env:
  PYTHON_VERSION: '3.x'
  NODE_VERSION: '18'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Setup Python
      uses: actions/setup-python@v4
      with:
        python-version: ${{ env.PYTHON_VERSION }}
    
    - name: Install and test
      run: |
        pip install mkdocs-material mkdocs-ai-summary-wcowin
        mkdocs build --strict
  
  deploy-staging:
    needs: test
    if: github.ref == 'refs/heads/develop'
    runs-on: ubuntu-latest
    environment: staging
    steps:
    - uses: actions/checkout@v4
    - name: Deploy to staging
      env:
        DEEPSEEK_API_KEY: ${{ secrets.STAGING_DEEPSEEK_API_KEY }}
      run: |
        pip install mkdocs-material mkdocs-ai-summary-wcowin
        mkdocs build
        # Deploy to staging environment
  
  deploy-production:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
    - uses: actions/checkout@v4
    - name: Deploy to production
      env:
        DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      run: |
        pip install mkdocs-material mkdocs-ai-summary-wcowin
        mkdocs build
        # Deploy to production environment

Cache Optimization Configuration

    - name: Cache AI summaries
      uses: actions/cache@v3
      with:
        path: .ai_cache
        key: ai-cache-${{ hashFiles('docs/**/*.md') }}-${{ hashFiles('mkdocs.yml') }}
        restore-keys: |
          ai-cache-${{ hashFiles('docs/**/*.md') }}-
          ai-cache-

Configuration

Basic Configuration

plugins:
  - ai-summary:
      # AI Service Configuration
      ai_service: "deepseek"          # Primary AI service
      fallback_services:               # Fallback services if primary fails
        - "openai"
        - "gemini"
      
      # Summary Configuration
      summary_language: "en"           # Summary language (zh/en)
      summary_length: "medium"         # Summary length (short/medium/long)
      
      # Caching Configuration
      cache_enabled: true              # Enable caching
      cache_expire_days: 30            # Cache expiration in days
      
      # File Selection
      enabled_folders:                 # Folders to process
        - "docs"
        - "guides"
      exclude_patterns:                # Patterns to exclude
        - "**/api/**"
        - "**/reference/**"
      exclude_files:                   # Specific files to exclude
        - "index.md"
        - "404.md"
      
      # Environment Configuration
      local_enabled: true              # Enable in local development
      ci_enabled: true                 # Enable in CI/CD
      ci_cache_only: false             # Only use cache in CI (no new API calls)
      ci_fallback_summary: true        # Use fallback summary in CI if no cache

Advanced Configuration

plugins:
  - ai-summary:
      # Custom API Endpoints
      custom_endpoints:
        deepseek:
          base_url: "https://api.deepseek.com"
          model: "deepseek-chat"
        openai:
          base_url: "https://api.openai.com/v1"
          model: "gpt-3.5-turbo"
      
      # Content Processing
      max_content_length: 8000         # Maximum content length for AI processing
      summary_position: "top"          # Position of summary (top/bottom)
      
      # Styling
      summary_style:
        theme: "material"               # Summary card theme
        show_icon: true                 # Show AI service icon
        show_language: true             # Show summary language

Environment Variables

Required API Keys

Variable	Description	Required
DEEPSEEK_API_KEY	DeepSeek API key	If using DeepSeek
OPENAI_API_KEY	OpenAI API key	If using OpenAI
GEMINI_API_KEY	Google Gemini API key	If using Gemini
GLM_API_KEY	GLM API key	If using GLM

Optional Configuration

Variable	Description	Default
AI_SUMMARY_DEBUG	Enable debug logging	false
AI_SUMMARY_TIMEOUT	API request timeout (seconds)	30
AI_SUMMARY_MAX_RETRIES	Maximum API retry attempts	3

CI/CD Integration

GitHub Actions

Add your API keys to GitHub Secrets and use them in your workflow:

name: Deploy Documentation

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: 3.x
      
      - name: Install dependencies
        run: |
          pip install mkdocs-material mkdocs-ai-summary-wcowin
      
      - name: Build documentation
        env:
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: mkdocs build
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

AI Services

Supported Services

Service	Model	Languages	Rate Limits
DeepSeek	deepseek-chat	zh, en	High
OpenAI	gpt-3.5-turbo, gpt-4	zh, en	Medium
Google Gemini	gemini-pro	zh, en	High
GLM	glm-4	zh, en	Medium

Service Selection Strategy

1. Primary Service: The main AI service specified in configuration
2. Fallback Services: Used if primary service fails or is unavailable
3. Automatic Retry: Built-in retry mechanism with exponential backoff
4. Cost Optimization: Intelligent service selection based on content length

Caching System

How It Works

• Content Hashing: Each page's content is hashed to detect changes
• Service Configuration: Cache is invalidated when AI service settings change
• Expiration: Configurable cache expiration (default: 30 days)
• CI Optimization: Special caching behavior for CI/CD environments

Cache Management

# Clear all cache
rm -rf .ai_cache/

# Clear expired cache (automatic during build)
# No manual action needed

Troubleshooting

Common Local Development Issues

1. API Key Not Found

Error Message:

Error: No valid API key found for service 'deepseek'
Warning: No available AI services, please check API key configuration

Solutions:

1. Check if .env file exists in project root
2. Verify API key name spelling (case-sensitive)
3. Validate API key format
4. Ensure .env file has no syntax errors

Verification Steps:

# Check .env file content
cat .env

# Verify environment variables are loaded
python -c "import os; print('DEEPSEEK_API_KEY:', os.getenv('DEEPSEEK_API_KEY', 'Not found'))"

2. Plugin Configuration Parameters Not Recognized

Error Message:

Config value: 'ai_service'. Warning: Unrecognised config name: ai_service

Solutions:

1. Ensure latest plugin version is installed:

   pip install --upgrade mkdocs-ai-summary-wcowin
   

2. Check plugin configuration format in mkdocs.yml:

   plugins:
     - ai-summary:  # Note the space after colon
         ai_service: "deepseek"
   

3. Network and Permission Issues

Error Message:

ConnectionError: Failed to connect to API endpoint
Timeout: Request timed out after 30 seconds

Solutions:

1. Check network connection
2. Verify API key validity
3. Increase timeout:

   AI_SUMMARY_TIMEOUT=60
   

4. Check firewall settings

4. Content Too Long Warning

Warning Message:

Warning: Content too long for AI processing, truncating...

Solutions:

1. Increase max content length in mkdocs.yml:

   plugins:
     - ai-summary:
         max_content_length: 12000
   

2. Split long pages into smaller ones
3. Use exclude_patterns to exclude overly long pages

GitHub Actions Deployment Issues

1. Secrets Configuration Error

Error Message:

Error: No valid API key found for service 'deepseek'

Solutions:

1. Check Repository Secrets configuration:

   • Go to GitHub repository → Settings → Secrets and variables → Actions
   • Verify secret names match environment variable names in workflow
   • Re-add potentially corrupted secrets

2. Verify workflow configuration:

   env:
     DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}  # Ensure names match
   

2. Build Failure

Error Message:

ERROR - Config value: 'plugins'. Error: The "ai-summary" plugin is not installed

Solutions:

1. Ensure plugin is installed in workflow:

   - name: Install dependencies
     run: |
       pip install mkdocs-material
       pip install mkdocs-ai-summary-wcowin  # Ensure this line is included
   

2. Check Python version compatibility:

   - name: Setup Python
     uses: actions/setup-python@v4
     with:
       python-version: '3.8'  # Or higher version
   

3. Deployment Permission Issues

Error Message:

Error: The process '/usr/bin/git' failed with exit code 128

Solutions:

1. Ensure GitHub Pages is enabled
2. Check GITHUB_TOKEN permissions
3. Verify branch name is correct (main/master)

Performance Optimization Issues

1. Long Build Times

Solutions:

1. Enable caching:

   plugins:
     - ai-summary:
         cache_enabled: true
         cache_expire_days: 30
   

2. Use caching in GitHub Actions:

   - name: Cache AI summaries
     uses: actions/cache@v3
     with:
       path: .ai_cache
       key: ai-cache-${{ hashFiles('docs/**/*.md') }}
   

3. Limit processing scope:

   plugins:
     - ai-summary:
         enabled_folders:
           - "docs/important"  # Only process important docs
         exclude_patterns:
           - "**/archive/**"   # Exclude archived content
   

2. Too Many API Calls

Solutions:

1. Optimize caching strategy
2. Use CI cache mode:

   plugins:
     - ai-summary:
         ci_cache_only: true  # Only use cache in CI
   

Debugging and Diagnostics

Enable Verbose Logging

Local Debugging:

# Enable debug mode
export AI_SUMMARY_DEBUG=true
mkdocs build --verbose

GitHub Actions Debugging:

- name: Build with debug
  env:
    AI_SUMMARY_DEBUG: true
  run: |
    mkdocs build --verbose

Check Plugin Status

# Check if plugin is correctly installed
pip show mkdocs-ai-summary-wcowin

# Check MkDocs plugin list
mkdocs --help

# Verify configuration file
mkdocs config

Test API Connection

Create test script test_api.py:

import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Test API keys
services = {
    'DEEPSEEK_API_KEY': os.getenv('DEEPSEEK_API_KEY'),
    'OPENAI_API_KEY': os.getenv('OPENAI_API_KEY'),
    'GEMINI_API_KEY': os.getenv('GEMINI_API_KEY'),
    'GLM_API_KEY': os.getenv('GLM_API_KEY')
}

for service, key in services.items():
    if key:
        print(f"✅ {service}: {key[:10]}...{key[-4:]}")
    else:
        print(f"❌ {service}: Not configured")

Run test:

python test_api.py

Getting Help

If the above solutions don't resolve your issue, please:

1. Check Detailed Logs: Enable debug mode for more information
2. Check Version Compatibility: Ensure you're using the latest plugin and MkDocs versions
3. Submit an Issue: Create an issue in the GitHub repository
4. Provide Information: Include error logs, configuration files, and environment information

Issue Template:

## Problem Description
[Describe the issue you're experiencing]

## Environment Information
- Operating System:
- Python Version:
- MkDocs Version:
- Plugin Version:

## Configuration File
```yaml
[Paste your mkdocs.yml configuration]

Error Logs

[Paste complete error messages]

Reproduction Steps

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
git clone https://github.com/Wcowin/Mkdocs-AI-Summary-Plus.git
cd Mkdocs-AI-Summary-Plus
pip install -e ".[dev]"

Running Tests

pytest

Code Quality

black .
flake8 .
mypy .

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes and version history.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

Acknowledgments

• MkDocs - The static site generator this plugin extends
• MkDocs Material - The beautiful theme that inspired our design
• All the AI service providers for making this plugin possible