mirror of
https://github.com/kbenestad/mdcms.git
synced 2026-06-18 15:24:32 +00:00
137 lines
5.2 KiB
Markdown
137 lines
5.2 KiB
Markdown
# MD-CMS
|
|
|
|
> Markdown-based static site publishing — no server, no database, no terminal required.
|
|
|
|
MD-CMS lets you write and publish a website entirely in markdown. Drop your `.md` files in a folder, run the build tool, upload the output to any static host, and you're done. All rendering happens in the browser.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
1) Download the latest [release](https://github.com/kbenestad/mdcms/releases).
|
|
- The contents of `mdcms-vNNN.zip` and `mdcms.zip` are identical. Choose whatever suits your preference.
|
|
3) Unzip the content in your project directory.
|
|
3) Make necessary changes to `config.yml` and add pages to `pages/`. *Please note: Links to other pages are in the form `pages/pagename.md`.*
|
|
4) Open the terminal in your project directory, and:
|
|
- Open MDCMS.py with `python3 mdcms.py`.
|
|
- Select option 3 to generate a `nav.yml` and `search.json` file.
|
|
- Open `nav.yml` in your text editor and make sure that the section and title names are correct.
|
|
- Once you're satisfied, you're ready to upload the content of `website/`. If you need a ZIP file, return to the terminal and select option 1.
|
|
|
|
---
|
|
|
|
## How it works
|
|
|
|
MD-CMS has two parts:
|
|
|
|
**`index.html`** — a single-file browser renderer. It reads your markdown files, config, and navigation at runtime and renders everything client-side. No build pipeline, no framework, no compilation step.
|
|
|
|
**`mdcms.py`** — a zero-dependency Python CLI tool. It scans your content, generates `nav.yml` and `search.json`, validates your config, and packages everything into a zip file ready for upload.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Write in markdown** — pages and posts with YAML frontmatter
|
|
- **Categories** — serve multiple versions of the same page (e.g. languages, destinations, variants) via `?cat=` URL parameter and a dropdown UI
|
|
- **Sections** — nested navigation defined in `nav.yml`; pages declare their section via frontmatter
|
|
- **Full-text search** — category-aware, generated at build time
|
|
- **Dynamic content tags** — embed post lists with date sorting, pagination, and year grouping using fenced `mdcms` code blocks
|
|
- **RTL support** — per-category text direction
|
|
- **Custom fonts per category** — load a font file from `assets/fonts/` when a category is selected
|
|
- **Light and dark mode** — fully themeable via `config.yml`
|
|
- **No server required** — everything is static; deploy to GitHub Pages, Codeberg Pages, Cloudflare Pages, Netlify, or any file host
|
|
- **Zero dependencies** — `mdcms.py` uses only the Python standard library
|
|
|
|
---
|
|
|
|
## File structure
|
|
|
|
```
|
|
mdcms.py ← build tool, run this
|
|
quickstart.md ← getting started guide
|
|
website/ ← everything in here gets deployed
|
|
index.html
|
|
config.yml
|
|
nav.yml
|
|
search.json
|
|
pages/
|
|
home.md
|
|
about.md
|
|
about.nb.md ← Norwegian variant of about.md
|
|
posts/
|
|
2025-01-01-my-first-post.md
|
|
assets/
|
|
images/
|
|
fonts/
|
|
```
|
|
|
|
The `website/` folder is your deployable site. `mdcms.py` lives outside it.
|
|
|
|
---
|
|
|
|
## Getting started
|
|
|
|
**Requirements:** Python 3 (standard library only). A modern browser.
|
|
|
|
1. Clone or download this repository.
|
|
2. Run `python3 mdcms.py` and choose **option 2** to build your config and folder structure from scratch.
|
|
3. Write your pages in `website/pages/` and posts in `website/posts/`.
|
|
4. Run `mdcms.py` again and choose **option 3** to generate `nav.yml` and `search.json`.
|
|
5. Choose **option 8** to start a local webserver and preview your site.
|
|
6. When ready to publish, choose **option 1** to validate, build, and export `website.zip`.
|
|
7. Upload the contents of `website.zip` to your static host.
|
|
|
|
> **Local preview note:** Open `index.html` via the built-in webserver (option 8), not by double-clicking the file. Browsers block local file access due to CORS restrictions.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Site behaviour is controlled by two YAML files in `website/`:
|
|
|
|
**`config.yml`** — site title, logo, default page, search settings, typography, layout dimensions, light/dark theme colours, and category definitions.
|
|
|
|
**`nav.yml`** — navigation structure. Sections are defined here; pages declare their section via `section-id` in frontmatter. Sections can be nested.
|
|
|
|
Both files are human-readable and comment-supported. The `mdcms.py` wizard generates them for you and can fill in missing values interactively.
|
|
|
|
---
|
|
|
|
## Categories
|
|
|
|
Categories let you publish multiple versions of the same page — different languages, regions, or product variants — under a single URL with a `?cat=` parameter.
|
|
|
|
Each variant is a separate file:
|
|
|
|
```
|
|
about.md ← default
|
|
about.en-gb.md ← British English variant
|
|
about.nb.md ← Norwegian variant
|
|
```
|
|
|
|
The category dropdown shows only categories for which a variant exists (or where a "not available" message is configured). All internal links preserve the active category.
|
|
|
|
---
|
|
|
|
## Tag system
|
|
|
|
Embed dynamic post lists in any page using fenced `mdcms` code blocks:
|
|
|
|
````markdown
|
|
```mdcms
|
|
posts-date-reversechronological
|
|
limit: 10
|
|
paginate: yes
|
|
```
|
|
````
|
|
|
|
Available tags cover chronological and reverse-chronological post lists, grouped by year, with date or datetime display, and configurable pagination.
|
|
|
|
---
|
|
|
|
## Licence
|
|
|
|
Apache 2.0 — see [LICENCE]((https://www.apache.org/licenses/LICENSE-2.0)).
|
|
|
|
© Kristian Benestad
|