a8fcc79ba9
The static <title> element previously showed "MD-CMS" before JavaScript loaded. The JS already sets document.title from config.sitename on boot, so clearing the initial value ensures the browser tab never displays the hardcoded string. |
||
|---|---|---|
| .github/workflows | ||
| app | ||
| docs | ||
| latest | ||
| sample-sites | ||
| .gitignore | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| mdcms.py | ||
| pyproject.toml | ||
| README.md | ||
| SECURITY.md | ||
MD-CMS
Write your content as .md files, run one command, and deploy to any static host. All rendering happens in the browser at runtime.
With the GitHub Actions workflow, you can automatically rebuild the navigation structure and search index on each commit.
How it works
MD-CMS has two parts:
The web app:
index.html— a single-file browser renderer. It reads your markdown, config, and nav at runtime and renders everything client-side. No compilation, no framework.config.yml— contains site configuration.nav.yml— navigation tree.search.json— supports site-wide search on static host.
The local app: mdcms — a CLI tool that scans your content, generates nav.yml
and search.json, and can wire up automatic builds via GitHub Actions.
Installation
Standalone binary
- Download from the latest release.
- Move the binary and make it executable
- Linux
- Download the latest mdcms
- Move it to
/usr/local/bin/:sudo mv mdcms /usr/local/bin/mdcms - Make it executable:
sudo chmod +x /usr/local/bin/mdcms
- Mac
- Download the latest mdcms
- Move it to
/usr/local/bin/:sudo mv mdcms /usr/local/bin/mdcms - Make it executable:
sudo chmod +x /usr/local/bin/mdcms - Remove the quarantine flag:
xattr -dr com.apple.quarantine /usr/local/bin/mdcms
- Windows
- Download the latest mdcms
- Move it to a permanent folder, e.g.
C:\tools\mdcms.exe - Add
C:\tools\to your PATH: Start → search"Environment Variables"→ edit thePath user variable→ addC:\tools\ - Open a new PowerShell window and verify:
mdcms --version
- Linux
Use
To get started, run mdcms register mysite to register the current working directory as the mysite MD-CMS project directory. You can also specify the project path: mdcms register mysite /path/to/mysiteNote.
If there is an existing MD-CMS instance in your specified directory, the app will register this site; if there is no MD-CMS instance present, it will download the latest version from the GitHub repo.
Add your pages, posts, and assets. Once you're ready to upload your site, run mdcms build mysite to update nav.yml and search.json. You can also run mdcms build --path to build the website without registering the site.
The final project directory can be uploaded to a static host of your choice.
File structure
[project directory]/
index.html ← renderer
config.yml ← site configuration and theme
nav.yml ← navigation structure
search.json ← search index
pages/ ← Put your permanent pages here
home.md ← Main page
...
posts/ ← Put your time-bound posts here
...
assets/ ← Holds directories for non-content files
required/ ← Logo, favicon, and icons go here.
...
images/ ← Images
...
fonts/ ← Fonts referenced in config.yml
...
files/ ← Files for download
...
IMPORTANT: All links are read from index.html in the root. Therefore, you must provide full paths for each file from the root.
Example: You want to put a link to page2.md in home.md. page2.md is in the same directory as home.md.
The correct link is therefore:
[Link text](pages/page2.md)
This does not link to page2.md:
[Link text](page2.md)
Further reading
For further documentation, refer to:
- docs/: Documentation relevant to this repo
- docs.benestad.net: Further help -- including an example of an MD-CMS site.
Licence
This software is © 2026 Kristian Benestad. Licensed under the Apache License, Version 2.0.