draftmk 0.7.1

Automate and preview MkDocs documentation projects with Docker.

draftmk

draftmk is an advanced command-line tool that automates the setup, management, and deployment of MkDocs-based documentation projects using Docker. It streamlines local previews, environment initialization, live editing, and supports CI/CD automation with flexible repository integration and configuration scaffolding for both public and internal documentation views.

Features

• One-command environment bootstrap with optional Git initialization
• CI-friendly flags: --no-git to skip Git setup, --repo to link existing repositories
• Automatic port assignment (avoids conflicts)
• Auto-generation of docs/index.md, mkdocs.public.yml, and mkdocs.internal.yml scaffolding
• Colorful CLI output for improved user experience
• Automatic Docker Compose setup via GitHub Gist download
• Friendly preview logs and automatic browser launching
• Supports seamless integration into CI pipelines

Installation

Install from PyPI:

pip install draftmk

Or add to a Poetry project:

poetry add draftmk

Requires Python ≥ 3.9, Docker, and Docker Compose.

Commands

init

Bootstraps a new DraftMk project.

draftmk init [<directory>] [--no-git] [--repo <repository-url>] [--yes] [--force-git] [--template <path-or-url>]

• Prompts for a directory name (defaults to draftmk-docs if not specified)
• Creates .draftmk/ structure and .env with available ports
• Generates default docs/index.md, mkdocs.public.yml, and mkdocs.internal.yml files for scaffolding
• Downloads docker-compose.yml from a GitHub Gist
• Optionally initializes a Git repository on the main branch unless --no-git is specified
• If --repo is provided, links the project to the existing Git repository

up

Initializes the project (if needed), pulls images, builds containers, and opens the browser.

draftmk up

• --no-browser: Do not open the frontend automatically

preview

Starts the full environment and shows Docker logs.

draftmk preview --open

• --open: Launches the frontend in your default browser

view

Launches the frontend in your browser using the port defined in .env.

draftmk view

• --print: Only print the preview URL instead of launching the browser

logs

Tails the last 50 lines of the .draftmk/logs/draftmk.log file.

draftmk logs

stop

Stops all DraftMk-related Docker containers.

draftmk stop

status

Shows the running status of all containers.

draftmk status

scaffold

Generates a new documentation project from a Copier template.

draftmk scaffold [--template <path-or-url>] [--quiet]

• --template: Specify a template path or URL (e.g., gh:your-org/your-template)
• --quiet: Suppress prompts and overwrite warnings (good for CI)

By default, it uses the internal template included with DraftMk.

Usage Examples for CI Automation

To bootstrap a project without Git initialization (useful in CI pipelines):

draftmk init --no-git

To bootstrap and link to an existing repository:

draftmk init --repo yourusername/yourrepo

Directory Structure

After running draftmk init, you will have:

.
├── .draftmk/
│   ├── config/
│   ├── site/
│   │   ├── public/
│   │   └── internal/
│   └── logs/
├── docs/
│   └── index.md
├── mkdocs.public.yml
├── mkdocs.internal.yml
├── .env
└── docker-compose.yml

Docker Images

DraftMk uses pre-built Docker images hosted on Docker Hub:

• Backend: jonmatum/draftmk-backend
• Frontend: jonmatum/draftmk-frontend
• Preview: jonmatum/draftmk-preview

Docker Compose Template

DraftMk no longer downloads a remote docker-compose.yml from a GitHub Gist.

Instead, the file is scaffolded using Copier templates (either internal or from a configured template repo).

Copier Template Support

DraftMk supports project scaffolding using Copier. You can generate a new documentation project structure using:

draftmk scaffold

By default, DraftMk uses an internal template bundled in the package.

To use a custom template instead, pass --template or define a .draftmk/settings.json file:

{
  "template_repo": "gh:your-org/your-template-repo"
}

This enables full customization of how your documentation project is initialized.

Requirements

• Python ≥ 3.9
• Docker
• Docker Compose

License

MIT © Jonatan Mata

---

echo "Pura Vida & Happy Coding!";