Zero-config static site builder for markdown blogs
Project description
mdwiki
mdwiki is a small static site builder that turns a directory tree of markdown files into a blog-ready HTML site.
It keeps the authoring model simple:
- directories become URL segments
- each markdown file becomes one HTML page
- local images referenced from markdown are copied into the output site
- index pages and tag pages are generated automatically
Install
Use uv:
uv tool install mdwiki
Or install from source:
uv sync
uv run mdwiki_exec ./example-posts ./dist
CLI
Build a site from a markdown source tree:
mdwiki_exec <source_dir> <dist_dir>
Show the built-in help or version:
mdwiki_exec --help
mdwiki_exec --version
Run the safe incremental mode with a newline-separated changed file list:
mdwiki_exec --changed-files changed.txt ./post ./dist
Example:
mdwiki_exec ./post ./dist
source_dir usually contains:
- markdown posts under dated folders such as
post/2024/04/03/demo.md - optional local images next to each markdown file
- optional
CNAME - optional
config.json
Safe Incremental Build
mdwiki now supports a safe incremental mode aimed at static blog workflows:
- if only markdown files under
post/changed, it rebuilds the affected detail pages - if images or other local assets under
post/changed, it rebuilds posts in the same folder - it always refreshes index pages and tag pages so listing pages stay correct
- if
config.json,CNAME, or files outside the source tree changed, it falls back to a full rebuild
The builder writes a manifest file named .mdwiki-build.json into the output directory.
If the previous output directory is restored in CI, the next run can reuse that manifest and avoid rewriting every article page.
Optional GoatCounter support
You can enable real pageview counters by adding goatcounter_script to your config.json:
{
"goatcounter_script": "<script data-goatcounter=\"https://drunkpig.goatcounter.com/count\" async src=\"//gc.zgo.at/count.js\"></script>"
}
When this field is present:
- article pages render a counter next to the slug
- index pages fetch and display per-article pageviews
When it is absent, mdwiki renders 未知 instead of fake random numbers.
Optional source markdown link
You can also expose the original markdown source for crawlers and readers:
{
"source_markdown_base_url": "https://raw.githubusercontent.com/drunkpig/drunkpig.github.io/master/post"
}
When this field is present, article pages will:
- add a standard
<link rel="alternate" type="text/markdown">tag in<head> - keep the raw markdown URL available to crawlers without showing a visible banner in the page body
Build date in footer
The default footer template renders build_version as a YYYYMMDD date during site generation.
Because GitHub Pages is built from source on every deploy, this date updates for all generated pages on each successful build.
GitHub Pages workflow
The recommended deployment model is:
- Keep markdown source in your repository.
- Restore the previous
dist/directory from cache. - Build the site in GitHub Actions.
- Upload the generated
dist/directory as a Pages artifact. - Deploy with
actions/deploy-pages.
Example workflow:
name: Build and Deploy Pages
on:
push:
branches: ["master"]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- uses: actions/cache/restore@v4
with:
path: dist
key: pages-dist-${{ github.ref_name }}-${{ github.run_id }}
restore-keys: |
pages-dist-${{ github.ref_name }}-
- name: Detect changed files
run: |
if [ "${{ github.event.before }}" = "0000000000000000000000000000000000000000" ]; then
: > changed.txt
else
git diff --name-only "${{ github.event.before }}" "${{ github.sha }}" > changed.txt
fi
- name: Install mdwiki
run: pip install mdwiki
- name: Build site
run: |
if [ -s changed.txt ]; then
mdwiki_exec --changed-files changed.txt ./post ./dist
else
mdwiki_exec ./post ./dist
fi
- uses: actions/cache/save@v4
if: github.event_name == 'push'
with:
path: dist
key: pages-dist-${{ github.ref_name }}-${{ github.run_id }}
Develop with uv
uv sync
uv run mdwiki_exec ./post ./dist
uv build
Publish to PyPI:
git tag -a v0.3.6 -m "Release v0.3.6"
git push origin master v0.3.6
Pushing a new v* tag triggers the bundled GitHub Actions release workflow, which builds the package with uv and publishes it to PyPI.
Notes
CNAMEis optional.- The bundled default theme is stored under
mdwiki/templates/default. mdwiki_execis the supported public CLI entrypoint.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file mdwiki-0.3.6.tar.gz.
File metadata
- Download URL: mdwiki-0.3.6.tar.gz
- Upload date:
- Size: 38.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fcc6836029b99de36a2e7f9a7183ca14d58c716d4154ef924c841532162890f9
|
|
| MD5 |
c553e4e5b2f2c6c402f7ede12354fe50
|
|
| BLAKE2b-256 |
3161aa32053b02c09cb06e24846c8666a7b384be455869b2e9c1a852606b9331
|
File details
Details for the file mdwiki-0.3.6-py3-none-any.whl.
File metadata
- Download URL: mdwiki-0.3.6-py3-none-any.whl
- Upload date:
- Size: 39.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
16fc5186b036d3655105e64b6d9d34f23da4f53c7833c41bee7106b2819a0759
|
|
| MD5 |
e5462edfcf12969587985b2bf6e24f2a
|
|
| BLAKE2b-256 |
5af1b837224d7a7479ce2e75056ec0456ebc561c92518eb63b791df773066177
|
