mkdocs-autoblog

🤖 AI-Powered Blog Promotion Generator for MkDocs

---

mkdocs-autoblog is an intelligent automation tool that leverages AI to generate SEO-optimized promotional blog posts for your MkDocs articles. It integrates with high-performance AI providers like Groq and Cerebras to analyze your content and create engaging summaries designed to boost traffic and visibility.

✨ Features

• 🎯 Smart Article Selection — AI intelligently selects articles that haven't been promoted recently, ensuring diverse and fresh content coverage.
• ⚡ High-Performance AI Providers — Supports Groq and Cerebras for blazing-fast inference with advanced reasoning capabilities.
• 📝 SEO-Optimized Output — Generates blog posts with proper structure, readability, and search engine optimization in mind.
• 🔄 Deduplication & History Tracking — Maintains a local history (.autoblog.json) to prevent repetitive processing and track promoted articles.
• 🎨 Customizable Templates — Uses Jinja2 templates for full control over prompt engineering and output formatting.
• 🐳 Docker Ready — Includes a Dockerfile for containerized deployments and CI/CD integration.
• 📦 MkDocs Integration — Seamlessly reads your MkDocs project structure via info.json and JSON feed configurations.

📋 Requirements

• Python 3.12+
• A valid API key for either Groq or Cerebras
• A deployed MkDocs site with JSON feed support
• An info.json file describing your project navigation structure

🚀 Quick Start

Installation

1. Clone the repository:

   git clone https://github.com/raineblog/mkdocs-autoblog.git
   cd mkdocs-autoblog

2. Install dependencies:

   pip install -r requirements.txt

3. Configure environment variables:

   Create a .env file in the project root:

   # Base URL of your deployed MkDocs site
   BASE_URL=https://your-blog-url.com
   
   # URL to your blog's JSON feed
   FEED_URL=https://your-blog-url.com/feed.json
   
   # AI Provider Configuration
   PROVIDER=groq
   PROVIDER_MODEL=llama3-70b-8192
   
   # API Keys (set the one corresponding to your provider)
   GROQ_API_KEY=your_groq_api_key
   CEREBRAS_API_KEY=your_cerebras_api_key

Usage

Run the main script:

python app.py

The script will:

1. Fetch your article list from the configured feed
2. Filter out recently processed articles using the history file
3. Use AI to select the best articles for promotion (2-3 articles)
4. Generate SEO-optimized promotional content for each selected article
5. Update the history file with processed articles

Docker Usage

Build and run using Docker:

docker build -t mkdocs-autoblog .
docker run --env-file .env -v $(pwd)/docs:/app/docs mkdocs-autoblog

Or use the pre-built image from GitHub Container Registry:

docker pull ghcr.io/raineblog/mkdocs-autoblog:latest

📁 Project Structure

mkdocs-autoblog/
├── app.py                 # Main entry point
├── utils/
│   ├── bot.py             # AI provider orchestration
│   ├── history.py         # History tracking and deduplication
│   ├── project.py         # MkDocs project utilities
│   └── provider/
│       ├── groq.py        # Groq API integration
│       └── cerebras.py    # Cerebras API integration
├── templates/
│   ├── prompt.md          # Article selection prompt template
│   ├── generate.md        # Content generation prompt template
│   └── template.md        # Output format template
├── src/
│   ├── schema.json        # JSON schema for structured AI output
│   └── .authors.yml       # Author metadata for generated posts
├── bin/
│   └── autoblog           # Docker entrypoint script
├── Dockerfile
├── requirements.txt
└── .env                   # Environment configuration (not tracked)

⚙️ Configuration

Environment Variables

Variable	Required	Description
BASE_URL	✅	Base URL of your deployed MkDocs site
FEED_URL	✅	URL to your blog's JSON feed
PROVIDER	✅	AI provider to use (groq or cerebras)
PROVIDER_MODEL	✅	Model identifier for the selected provider
GROQ_API_KEY	⚠️	API key for Groq (required if using Groq)
CEREBRAS_API_KEY	⚠️	API key for Cerebras (required if using Cerebras)

Supported AI Providers

Provider	Features	Notes
Groq	High-speed inference, reasoning support	Recommended for production use
Cerebras	Advanced AI capabilities	Alternative option

🔧 Customization

Templates

The templates/ directory contains Jinja2 templates that control the AI prompts:

• prompt.md — Template for the article selection prompt
• generate.md — Template for the content generation prompt
• template.md — Format specification for generated blog posts

Output Schema

The src/schema.json file defines the JSON schema for structured AI output, ensuring consistent and parseable responses.

🤝 Contributing

This is a personal project maintained primarily for my own workflow. While I appreciate and welcome bug reports and corrections, I am not actively seeking new feature requests or major contributions at this time.

If you find a bug or have a suggestion:

• Bug reports: Please open an issue with a clear description
• Pull requests: Bug fixes are welcome; please discuss feature additions first

📄 License

This project is licensed under the MIT License.

---

_{📝 This README was generated by Antigravity (Claude Opus 4.5, Thinking) and reviewed by the maintainer.}