draftmk 0.8.1

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)
• Auto-generation of docs/index.md, mkdocs.public.yml, and mkdocs.internal.yml scaffolding
• 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 internal and 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

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>] [--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
• Initializes .draftmk structure and .env file with dynamic ports
• See Git Initialization Logic
• See Project Scaffolding with Copier
• Uses --force to bypass directory emptiness check
• --yes is deprecated and replaced with --force

You can override the default internal Copier template with --template, or configure one in .draftmk/settings.json. 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

When initializing, draftmk auto-generates dynamic ports for the frontend, backend, and preview services (unless set via environment variables). These values are stored in a .env file.

To regenerate .env, delete it and rerun draftmk init.

Directory Structure

.
├── .draftmk/
│   ├── config/
│   │   ├── mkdocs.internal.yml
│   │   └── mkdocs.public.yml
│   ├── site/
│   │   ├── public/
│   │   └── internal/
│   ├── logs/
│   │   └── draftmk.log
│   └── settings.json  # optional template override
├── 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. 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.

• 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.

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).

Requirements

• Python ≥ 3.9
• Docker
• Docker Compose

Directory Structure

.
├── .draftmk/
│   ├── config/
│   │   ├── mkdocs.internal.yml
│   │   └── mkdocs.public.yml
│   ├── site/
│   │   ├── public/
│   │   └── internal/
│   ├── logs/
│   │   └── draftmk.log
│   └── settings.json  # optional, not used by default anymore
├── docs/
│   └── index.md
├── .env
├── docker-compose.yml

Template Source

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

• Internal templates have been removed
• Custom templates can still be provided via --template or .draftmk/settings.json
• Default behavior uses: gh:jonmatum/draftmk-copier-templates

License

MIT © Jonatan Mata

---

echo "Pura Vida & Happy Coding!";