mkdocs-flow 0.1.0

Automated Documentation Project Generator - Create beautiful MkDocs documentation projects with ease

DocuFlow

Automated Documentation Project Generator - Create beautiful MkDocs documentation projects with PDF export and version management

DocuFlow is a powerful CLI tool that automates the creation of professional documentation projects using MkDocs and the Material theme. It handles everything from project setup to Git repository creation, CI/CD configuration, PDF generation, and versioned documentation deployment.

✨ Features

Core Features

• 🚀 Quick Project Setup - Generate complete documentation projects in seconds
• 🎨 Beautiful Templates - Pre-configured MkDocs Material themes
• 🔧 Git Integration - Automatic GitHub/GitLab repository creation
• 📦 CI/CD Ready - GitHub Actions and GitLab CI configurations included
• 🎯 Multiple Templates - Choose from basic or full-featured setups
• 🔐 Secure Authentication - Token management with keyring integration
• 📱 Rich CLI - Beautiful terminal interface with progress indicators

PDF Generation

• 📄 PDF Export - Generate professional PDFs from your markdown documentation
• 📚 Version History - Automatically include git tag history in PDFs
• 🔗 Table of Contents - Clickable TOC with customizable depth
• 🖼️ Image Embedding - Base64 image encoding for standalone PDFs
• 📊 Mermaid Diagrams - Optional diagram rendering to images
• 📦 Multi-Section PDFs - Generate different PDFs from different doc sections
• 🎁 Release Packages - Create ZIP files with PDFs and additional files

Version Management

• 🏷️ Versioned Docs - Full integration with mike for versioned documentation
• 🔄 Git Tag Sync - Automatic alignment between git tags and documentation versions
• 📌 Version Aliases - Support for "latest", "stable", and custom aliases
• 🌐 Version Selector - Automatic version picker in your documentation site
• 🚀 Automated Deployment - CI/CD workflows handle versioned deployments automatically

🚀 Quick Start

Installation

# Install with pip
pip install mkdocs-flow

# Or with Poetry
poetry add mkdocs-flow

# Install with PDF generation support
pip install "mkdocs-flow[diagrams]"  # Includes Mermaid diagram rendering

System Requirements for PDF Generation:

Ubuntu/Debian:

sudo apt-get install -y libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev libcairo2

macOS:

brew install cairo pango gdk-pixbuf libffi

Basic Usage

# Initialize a new documentation project
docuflow init my-awesome-docs

# Navigate to your project
cd my-awesome-docs

# Serve documentation locally
docuflow serve

# Build documentation
docuflow build

# Create a versioned release
docuflow version-create --version 1.0 --alias latest

# Generate PDFs
docuflow generate-pdf

# Deploy to GitHub/GitLab Pages (with versioning)
git push origin main
git tag 1.0.0
git push origin 1.0.0  # Triggers automatic versioned deployment

📖 Documentation

Commands

docuflow init [PROJECT_NAME]

Initialize a new documentation project with interactive setup.

Options:

• --name TEXT - Project name
• --description TEXT - Project description
• --author TEXT - Author name
• --email TEXT - Author email
• --git-provider [github|gitlab] - Git provider
• --private - Create private repository
• --template [basic|full] - Project template
• --no-remote - Skip remote repository creation
• --config-file PATH - Configuration file

Example:

docuflow init my-project \
  --description "My awesome project documentation" \
  --author "John Doe" \
  --email "[e-mail]" \
  --template full \
  --private

docuflow serve [PROJECT_PATH]

Serve documentation locally for development.

Example:

docuflow serve ./my-project

docuflow build [PROJECT_PATH]

Build documentation site.

Options:

• --clean - Clean build directory before building

Example:

docuflow build --clean

docuflow deploy [PROJECT_PATH]

Deploy documentation to GitHub/GitLab Pages.

Options:

• --force - Force deployment without confirmation

Example:

docuflow deploy --force

docuflow config

Manage DocuFlow configuration and authentication tokens.

docuflow templates

List available project templates.

docuflow version-create

Create a new documentation version with mike and git tag.

Options:

• --version, -v TEXT - Version number (e.g., 1.0, 1.0.0)
• --title TEXT - Version title
• --alias, -a TEXT - Version aliases (can be used multiple times)
• --no-tag - Do not create git tag
• --message, -m TEXT - Git tag message

Example:

# Create version 1.0 with "latest" alias
docuflow version-create --version 1.0 --alias latest

# Create version with custom title and multiple aliases
docuflow version-create \
  --version 2.0 \
  --title "Version 2.0 - Major Release" \
  --alias latest \
  --alias stable

# Interactive mode
docuflow version-create

docuflow version-list

List all versions and check alignment between git tags and mike versions.

Example:

docuflow version-list

Shows a table with:

• ✓ Aligned versions (both git tag and mike version exist)
• ⚠ Git-only tags (no corresponding mike version)
• ⚠ Mike-only versions (no corresponding git tag)

docuflow generate-pdf

Generate PDF documentation from markdown files.

Arguments:

• SECTIONS - Section names to generate (optional, defaults to all)

Options:

• --tag, -t TEXT - Git tag/version to use
• --output-dir PATH - Output directory (default: pdfs)

Examples:

# Generate all configured PDFs
docuflow generate-pdf

# Generate specific sections
docuflow generate-pdf user-guide api-reference

# Generate for a specific version
docuflow generate-pdf --tag 1.0.0

# Custom output directory
docuflow generate-pdf --output-dir releases/v1.0

Generated projects also include a standalone generate_pdf.py script:

# In your project directory
poetry run python generate_pdf.py --tag 1.0

Templates

Basic Template

• Minimal setup with essential pages and plugins
• Plugins: search, awesome-pages, mermaid2
• Perfect for simple documentation needs

Full Template

• Comprehensive structure with all features enabled
• Plugins: search, awesome-pages, mermaid2, git-revision-date-localized, minify
• Advanced features and optimizations included

Configuration

DocuFlow stores configuration in ~/.docuflow/config.yml. You can customize:

• Default git provider (GitHub/GitLab)
• Default theme and template
• Repository visibility preferences
• Plugin configurations

Authentication

DocuFlow supports secure token storage using keyring:

# Configure tokens interactively
docuflow config

# Or set environment variables
export GITHUB_TOKEN="your_github_token"
export GITLAB_TOKEN="your_gitlab_token"

PDF Configuration

Generated projects include a pdf_config.yml file for customizing PDF generation:

# PDF Export Configuration
sections:
  - name: user-guide
    title: "User Guide"
    output: "user-guide.pdf"
    docs_dir: "docs/sections/user-guide"

  - name: api-reference
    title: "API Reference"
    output: "api-reference.pdf"
    docs_dir: "docs/sections/api-reference"

  - name: full-documentation
    title: "Complete Documentation"
    output: "documentation.pdf"
    docs_dir: "docs"

# Version history settings
include_version_history: true

# Table of contents settings
include_toc: true
toc_depth: 3

# Image handling
embed_images: true

# Mermaid diagram rendering (requires playwright)
render_mermaid: false

# Release packaging
create_release_zip: false
release_includes:
  - "*.g4"
  - "*.ebnf"

Version Management with Mike

Generated projects automatically include mike configuration in mkdocs.yml:

extra:
  version:
    provider: mike

The GitHub Actions workflow is pre-configured to:

• Deploy versioned documentation on tag pushes
• Update the "latest" alias automatically
• Maintain version history with a version selector

Workflow:

1. Develop documentation on the main branch
2. Create a version: docuflow version-create --version 1.0 --alias latest
3. Push changes and tags: git push && git push --tags
4. GitHub Actions automatically deploys the versioned documentation
5. Users can select versions from the documentation site

🛠️ Development

Setup Development Environment

# Clone the repository
git clone https://github.com/yourusername/docuflow.git
cd docuflow

# Install dependencies
poetry install

# Install pre-commit hooks
pre-commit install

# Run tests
poetry run pytest

# Run linting
poetry run black src tests
poetry run isort src tests
poetry run flake8 src tests
poetry run mypy src

Project Structure

docuflow/
├── src/docuflow/              # Source code
│   ├── __init__.py
│   ├── cli.py                 # CLI interface
│   ├── config.py              # Configuration management
│   ├── git_manager.py         # Git operations
│   ├── models.py              # Data models (including PDF config)
│   ├── project_manager.py     # Project orchestration
│   ├── template.py            # Template generation
│   ├── export_utils.py        # Git tag & file utilities
│   ├── pdf_generator.py       # PDF generation engine
│   ├── version_manager.py     # Version management (mike)
│   ├── mermaid_renderer.py    # Mermaid diagram rendering
│   └── templates/             # Project templates
│       ├── export_utils.py.template
│       ├── generate_pdf.py.template
│       └── mermaid_renderer.py.template
├── tests/                     # Test suite
│   ├── test_cli.py
│   ├── test_export_utils.py
│   ├── test_pdf_generator.py
│   ├── test_version_manager.py
│   └── ...
├── docs/                      # Documentation
├── pyproject.toml             # Poetry configuration
├── README.md
└── IMPLEMENTATION_SUMMARY.md  # Implementation details

Generated Project Structure:

When you create a project with DocuFlow, it includes:

my-project/
├── docs/                      # Documentation source
├── mkdocs.yml                 # MkDocs config (with mike)
├── pyproject.toml             # Dependencies (includes mike)
├── pdf_config.yml             # PDF generation config
├── export_utils.py            # Export utilities
├── generate_pdf.py            # PDF generation script
├── mermaid_renderer.py        # Mermaid support
├── .github/workflows/
│   └── deploy-docs.yml        # CI/CD with mike deployment
└── scripts/
    ├── build.sh
    └── serve.sh

Testing

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src/docuflow

# Run specific test file
poetry run pytest tests/test_cli.py

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Run the test suite (poetry run pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📄 License

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

🙏 Acknowledgments

Core Technologies

• MkDocs - The documentation generator
• Material for MkDocs - The beautiful theme
• Click - The CLI framework
• Rich - Beautiful terminal output

PDF & Versioning

• WeasyPrint - PDF generation from HTML/CSS
• Mike - MkDocs version management
• Pillow - Image processing
• Playwright - Mermaid diagram rendering

Development Tools

• Poetry - Dependency management
• Pytest - Testing framework
• Black - Code formatting

📞 Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

🆕 What's New

Version 0.2.0 - PDF & Versioning Support

DocuFlow now includes comprehensive PDF generation and version management capabilities!

New Features:

• ✅ Generate professional PDFs from markdown with version history
• ✅ Full mike integration for versioned documentation
• ✅ Automatic git tag and version alignment
• ✅ Mermaid diagram rendering in PDFs
• ✅ Multi-section PDF export
• ✅ Release packaging with ZIP files

New Commands:

• docuflow version-create - Create versioned releases
• docuflow version-list - Check version alignment
• docuflow generate-pdf - Generate PDFs

See IMPLEMENTATION_SUMMARY.md for complete implementation details and the PDF_VERSIONING_MIGRATION_GUIDE.md for the original feature specifications.

---

Made with ❤️ for the open source community