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
Use uv:
uv tool install mdwikiOr install from source:
uv sync
uv run mdwiki_exec ./example-posts ./distBuild 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 --versionRun the safe incremental mode with a newline-separated changed file list:
mdwiki_exec --changed-files changed.txt ./post ./distExample:
mdwiki_exec ./post ./distsource_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
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.
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.
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
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.
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 }}uv sync
uv run mdwiki_exec ./post ./dist
uv buildPublish to PyPI:
git tag -a v0.3.7 -m "Release v0.3.7"
git push origin master v0.3.7Pushing a new v* tag triggers the bundled GitHub Actions release workflow, which builds the package with uv and publishes it to PyPI.
CNAMEis optional.- The bundled default theme is stored under
mdwiki/templates/default. mdwiki_execis the supported public CLI entrypoint.