draftmk 0.7.2

DraftMk CLI automates setup and preview of MkDocs documentation using Docker, dynamic ports, and Copier templates.

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)
• Initializes .draftmk structure and .env file with dynamic ports
• Automatically scaffolds the project using Copier (internal template by default, or override with --template).
• 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

You can override the default internal Copier template with --template, or configure one in .draftmk/settings.json.

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

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

.
├── .draftmk/
│   ├── config/
│   ├── site/
│   │   ├── public/
│   │   └── internal/
│   ├── logs/
│   └── settings.json  # optional template override
├── 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 scaffolds projects using Copier during draftmk init. To override the template, pass --template or define .draftmk/settings.json.

{
  "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!";