Getting Started

Install

Install mkpages from PyPI:

pip install mkpages

For local development in this repository:

pip install -e '.[dev]'

Basic usage

Generate a Jekyll source tree from the current directory:

mkpages build

Generate from a docs/ folder into .mkpages/:

mkpages build docs/

Preview a Markdown tree in one step:

mkpages preview docs/

mkpages preview watches the content tree, rebuilds when files change, and refreshes the browser automatically through Jekyll live reload.

The same shortcut also works without an explicit subcommand:

mkpages docs/

Configure site metadata in mkpages.yml at the content root:

title: My Docs
description: Notes and documentation for the project.
url: https://example.com
theme: dark
favicon: assets/favicon.png

What gets generated

The output directory contains:

• _config.yml
• _layouts/default.html
• _includes/
• generated Markdown pages with front matter
• copied non-Markdown assets
• assets/site.css
• .mkpages-output

Hidden files and hidden directories in the content root are ignored by default.

Next steps

Once the output exists, point a Jekyll build at it. See GitHub Pages for a typical workflow.

For local preview with Jekyll installed:

mkpages build docs/
mkpages serve

mkpages serve uses the existing .mkpages output and opens the preview URL in your default browser when possible. It also enables Jekyll live reload for changes that happen inside the generated .mkpages tree.

Mermaid diagrams

Fenced code blocks marked as mermaid are rendered automatically in the generated site.

flowchart TD
  A[Markdown] --> B[mkpages]
  B --> C[Jekyll]
  C --> D[Static site]