MkDocs Exporter

A specialized, Docker-based tool for exporting MkDocs documentation to PDF (via Selenium/Chrome) and LaTeX. Built on Alpine Linux for efficiency and tailored for the MkDocs Material theme.

⚠️ Disclaimer: This project is personally maintained by RainPPR for specific internal use cases. It overrides strict formatting rules and is not designed for general-purpose compatibility.

• Feature Requests: NOT Accepted. The project scope is limited to the author's needs.
• Contributions: Bug fixes and documentation corrections are welcome.
• Support: Provided "as-is" with no guarantees.

✨ Features

• Dockerized Environment: Runs in a lightweight python:alpine container.
• PDF Export: Uses headless Chromium (Selenium) to scrape and print pages to PDF with high fidelity.
• Optimize for Performance:
  • Includes a customized mlib_download.py downloader with low-resource tuning (memory management, eager loading, flag optimizations).
  • Supports concurrently downloading multiple pages.
• Integrated Plugin Stack:
  • Pre-installed with a curated list of plugins: mkdocs-material, mkdocs-jupyter, mkdocs-katex-ssr, mkdocs-table-reader-plugin, and more.
  • Includes custom LaTeX template support (template.tex).
• Automated Workflow:
  • Generates mkdocs.yml dynamically from info.json.
  • Builds the site, starts a local server, captures PDFs, and optionally compiles to a single document.

🛠️ Prerequisites

• Docker installed on your machine.
• A compatible MkDocs project structure (containing docs/ and info.json).

🚀 Installation

Clone the repository and build the Docker image:

git clone https://github.com/RainPPR/mkdocs-exporter.git
cd mkdocs-exporter
make build
# OR directly with docker
docker build -t mkdocs-exporter .

📖 Usage

1. Project Structure

Ensure your documentation project has an info.json file in the root. This file acts as the manifest for the export process, defining metadata, navigation, and export targets.

2. Run the Exporter

Mount your project directory to /app in the container:

docker run --rm \
  -v "$(pwd):/app" \
  -e MAX_THREADS=4 \
  mkdocs-exporter

• -v "$(pwd):/app": Maps your current directory to the container's working directory.
• -e MAX_THREADS=4: (Optional) Sets the concurrency level for PDF downloading. Default is 4.

3. Output

Artifacts (PDFs, compiled LaTeX files) will typically be generated in a build/ directory or as defined in your info.json export configuration.

⚙️ Configuration

Environment Variables

Variable	Default	Description
MAX_THREADS	4	Number of concurrent Selenium workers for downloading PDFs.

Dependencies

The environment is defined in requirements.txt. Key packages include:

• mkdocs-material (Theme)
• selenium (PDF Generation)
• mkdocs-katex-ssr (Math rendering)
• pymdown-extensions (Markdown extensions)

🤝 Contributing

As stated, this project is primarily for personal use.

• Do: Submit Pull Requests for obvious bugs, crash fixes, or spelling errors.
• Don't: Submit requests for new features, support for other themes, or major refactors unless strictly necessary.

📄 License

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

---

This README was generated by Google DeepMind's Antigravity (Gemini 3.0 Pro) model and verified by a human.