draftmk 0.8.5

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, live editing, and environment setup. It also 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)
• Colorful CLI output for improved user experience
• Docker Compose configuration scaffolded from templates
• Friendly preview logs and automatic browser launching
• Supports seamless integration into CI pipelines
• Supports remote Copier templates

Quick Start

draftmk init my-docs
cd my-docs
draftmk up

Make sure Docker and Python ≥ 3.9 are installed.

This scaffolds your project, starts Docker services, and opens the frontend in your browser. Edit content in docs/index.md and see it live instantly!

Installation

Install from PyPI:

pip install draftmk

Commands

init

Bootstraps a new DraftMk project.

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

If no directory is passed, you'll be prompted to enter one. Default is draftmk-docs.

• If no <directory> is given, user is prompted (default is draftmk-docs)
• --repo defaults to the directory name
• Scaffolds project using a Copier template (all configuration and file generation is handled by the template)
• See Git Initialization Logic
• See Project Scaffolding with Copier
• Uses --force to bypass directory emptiness check

You can override the default Copier template with --template. See Project Scaffolding with Copier.

up

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

draftmk up

• Runs init automatically if .env is missing
• --no-browser: Do not open the frontend automatically

preview

Starts the full environment and shows Docker logs.

draftmk preview --open

• Assumes project is already initialized
• --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
• --print will only show the frontend URL

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

.env Handling and Port Assignment

During init, DraftMk only passes dynamically discovered port values (and other variables) to the Copier template. The Copier template is entirely responsible for generating the .env file and all configuration scaffolding. The actual content and structure of .env is determined by the Copier template in use.

Directory Structure

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

Git Initialization Logic

• --no-git: Skip Git setup entirely
• --force-git: Force Git init even if .git exists
• If neither flag is set:
  • CLI prompts user interactively (default is yes)
  • Initializes on main branch

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

Docker Images

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

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

Project Scaffolding with Copier

DraftMk scaffolds projects using Copier during draftmk init. The default template is gh:jonmatum/draftmk-copier-templates.

All configuration and file generation—including .env, docs/index.md, and all MkDocs config files—is handled exclusively by the Copier template. DraftMk CLI does not generate or modify these files directly.

To override the template, pass --template with a Copier-compatible repo or path.

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

• Copier variables supported include:

  project_name: "Your Docs"
  repo_name: "your-org/your-repo"
  site_url: "https://example.com"
  vite_env: "production"
  

• DraftMk pre-fills dynamic ports and environment for the template using Copier's data injection.

Make sure the template repo is tagged if you're using a versioned reference.

Requirements

• Python ≥ 3.9
• Docker
• Docker Compose

Template Source

As of the latest version, DraftMk exclusively uses the public Copier template repository for project scaffolding by default.

• Custom templates can still be provided via --template
• Default behavior uses: gh:jonmatum/draftmk-copier-templates

License

MIT © Jonatan Mata

---

echo "Pura Vida & Happy Coding!";