draftmk 0.9.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, 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 in the range 3000-3999 (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
• Automatic version checking to notify about updates

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 <org/repo>] [--force] [--force-git] [--template <path-or-url>]

• If no <directory> is given, user is prompted (default is draftmk-docs)
• Project names must use lowercase letters, numbers, and hyphens only (e.g., draftmk-docs123)
• --repo specifies the repository name in format "org/repo" (defaults to the directory name)
• Scaffolds project using a Copier template (all configuration and file generation is handled by the template)
• --force bypasses directory emptiness check
• --force-git initializes Git even if a .git directory exists

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 [--no-browser]

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

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

Error Handling and Logging

DraftMk implements comprehensive error handling and logging:

• All operations are logged to .draftmk/logs/draftmk.log
• Colorful terminal output using the Rich library provides clear status indicators
• Dependency checks ensure Docker and Docker Compose are installed
• Graceful handling of keyboard interrupts (Ctrl+C)
• Detailed error messages for common issues:
  • Missing dependencies
  • Port conflicts
  • Directory permission issues
  • Template errors

The logs command provides easy access to the log file for troubleshooting:

draftmk logs

Project Name Validation

DraftMk enforces strict project name validation:

• Names must use lowercase letters, numbers, and hyphens only
• Names must follow the pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
• Examples of valid names: draftmk-docs, my-project-123
• Examples of invalid names: Docs (uppercase), docs_project (underscore), my- (trailing hyphen)

This ensures compatibility with Docker container naming, Git repositories, and URL paths.

.env Handling and Port Assignment

During init, DraftMk discovers available ports in the range 3000-3999 and passes these values (along with 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

DraftMk supports seamless integration into CI pipelines with several CI-friendly options:

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

draftmk init --no-git

For automated documentation builds in CI:

# Example CI workflow
draftmk init --no-git --repo your-org/your-repo
draftmk up --no-browser
# Run additional build or deployment steps

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. These images are referenced in the docker-compose.yml file generated by the Copier template:

• Backend: jonmatum/draftmk-backend - Handles the MkDocs build process
• Frontend: jonmatum/draftmk-frontend - Serves the web interface
• Preview: jonmatum/draftmk-preview - Provides live preview functionality

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 passed to the template include:

  project_name: "DraftMk Docs"
  repo_name: "your-org/your-repo"
  site_url: "https://example.com"
  vite_env: "production"
  frontend_port: <dynamically assigned>
  backend_port: <dynamically assigned>
  preview_port: <dynamically assigned>
  

• 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

Python Dependencies

• rich (≥14.0.0)
• psutil (≥7.0.0)
• copier (≥9.0.0)

Dependency Checking

DraftMk performs automatic dependency checking before executing commands:

def check_prerequisites():
    required = ["docker", "docker-compose"]
    for cmd in required:
        if not shutil.which(cmd):
            logger.error(f"Missing required command: {cmd}")
            raise MissingDependencyError(f"Required command '{cmd}' not found.")

This ensures that Docker and Docker Compose are installed before attempting any operations, providing clear error messages if dependencies are missing.

Port Discovery Algorithm

DraftMk uses a sophisticated port discovery algorithm to find available ports:

• Scans for open ports in the range 3000-3999
• Uses psutil to check for listening ports
• Falls back to socket binding tests if permission issues occur
• Ensures no port conflicts between frontend, backend, and preview services
• Passes discovered ports to the Copier template for configuration

Command Execution Flow

The typical command execution flow in DraftMk is:

1. Dependency Check: Verify Docker and Docker Compose are installed
2. Environment Setup: Create necessary directories and log files
3. Configuration: Generate or read configuration files
4. Docker Operations: Pull images, start containers, or check status
5. User Feedback: Provide colorful terminal output and browser launching

Version Checking

DraftMk automatically checks for updates when run. If a newer version is available, it will display a notification with upgrade instructions. This check is performed silently and will not interrupt normal operation if it fails.

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