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
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
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 visible link at the top of the article body
- add a standard
<link rel=\"alternate\" type=\"text/markdown\">tag in<head>
Build date in footer
The default footer template now renders build_version as a YYYY-MM-DD 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.
- 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@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- uses: actions/configure-pages@v5
- name: Install mdwiki
run: pip install mdwiki
- name: Build site
run: mdwiki_exec ./post ./dist
- uses: actions/upload-pages-artifact@v3
with:
path: ./dist
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
steps:
- id: deployment
uses: actions/deploy-pages@v4
Develop with uv
uv sync
uv run mdwiki_exec ./post ./dist
uv build
Publish to PyPI:
git tag -a v0.3.3 -m "Release v0.3.3"
git push origin master v0.3.3
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.5.tar.gz.
File metadata
- Download URL: mdwiki-0.3.5.tar.gz
- Upload date:
- Size: 36.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0e55434adc0bbeb8aaf9e71b08c6c75d2b84b1ae9bf21bf9093ae47b33d3fe25
|
|
| MD5 |
2b9c9c39df378dae502dceb3b08f2afa
|
|
| BLAKE2b-256 |
be94b431a83fca3547cff8957c1a97ad39b943263b3cb80444eb0617f8750f48
|
File details
Details for the file mdwiki-0.3.5-py3-none-any.whl.
File metadata
- Download URL: mdwiki-0.3.5-py3-none-any.whl
- Upload date:
- Size: 38.1 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 |
cca10c3bbc353700352f2953dbe5bca3051105623c08fadcf15aeb907f3ceb3e
|
|
| MD5 |
5bd8d5758e5e2a01b48832747d1ce768
|
|
| BLAKE2b-256 |
8f5d8413c5d480a53143649bf0542bc8650cb052ef4417c10ca9779c5f5c985a
|
