mirror of
https://github.com/kbenestad/mdcms.git
synced 2026-06-18 15:24:32 +00:00
Updated readme and release structure
This commit is contained in:
capthailand
parent
1657228b47
commit
d0bf37a3f0
4 changed files with 78 additions and 100 deletions
178
README.md
178
README.md
|
|
@ -1,128 +1,106 @@
|
||||||
# MD-CMS
|
# MD-CMS
|
||||||
|
|
||||||
> Markdown-based static site publishing
|
Write your content as `.md` files, run one command, and deploy to any static host. All rendering happens in the browser at runtime.
|
||||||
|
|
||||||
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.
|
With the GitHub Actions workflow, you can automatically rebuild the navigation structure and search index on each commit.
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
1) Download the latest [release](https://github.com/kbenestad/mdcms/releases) for your
|
|
||||||
---
|
|
||||||
|
|
||||||
|
- - -
|
||||||
## How it works
|
## How it works
|
||||||
|
|
||||||
MD-CMS has two parts:
|
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.
|
The web app:
|
||||||
|
|
||||||
**`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.
|
- `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.
|
||||||
|
|
||||||
## Features
|
## Installation
|
||||||
|
|
||||||
- **Write in markdown** — pages and posts with YAML frontmatter
|
**Standalone binary**
|
||||||
- **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
|
|
||||||
|
|
||||||
---
|
1. Download from the
|
||||||
|
[latest release](https://github.com/kbenestad/mdcms/releases/latest).
|
||||||
|
2. Move the binary and make it executable
|
||||||
|
- Linux
|
||||||
|
- Download the [latest mdcms](latest/linux/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](latest/macos/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](latest/windows/mdcms.exe)
|
||||||
|
- Move it to a permanent folder, e.g. `C:\tools\mdcms.exe`
|
||||||
|
- Add `C:\tools\` to your PATH: Start → search `"Environment Variables"` → edit the `Path user variable` → add `C:\tools\`
|
||||||
|
- Open a new PowerShell window and verify: `mdcms --version`
|
||||||
|
|
||||||
|
## 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
|
## File structure
|
||||||
|
|
||||||
```
|
```
|
||||||
mdcms.py ← build tool, run this
|
[project directory]/
|
||||||
quickstart.md ← getting started guide
|
index.html ← renderer
|
||||||
website/ ← everything in here gets deployed
|
config.yml ← site configuration and theme
|
||||||
index.html
|
nav.yml ← navigation structure
|
||||||
config.yml
|
search.json ← search index
|
||||||
nav.yml
|
|
||||||
search.json
|
pages/ ← Put your permanent pages here
|
||||||
pages/
|
home.md ← Main page
|
||||||
home.md
|
...
|
||||||
about.md
|
|
||||||
about.nb.md ← Norwegian variant of about.md
|
posts/ ← Put your time-bound posts here
|
||||||
posts/
|
...
|
||||||
2025-01-01-my-first-post.md
|
|
||||||
assets/
|
assets/ ← Holds directories for non-content files
|
||||||
images/
|
required/ ← Logo, favicon, and icons go here.
|
||||||
fonts/
|
...
|
||||||
|
|
||||||
|
images/ ← Images
|
||||||
|
...
|
||||||
|
|
||||||
|
fonts/ ← Fonts referenced in config.yml
|
||||||
|
...
|
||||||
|
|
||||||
|
files/ ← Files for download
|
||||||
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
The `website/` folder is your deployable site. `mdcms.py` lives outside it.
|
**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`.
|
||||||
|
|
||||||
## 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:
|
|
||||||
|
|
||||||
|
The correct link is therefore:
|
||||||
```
|
```
|
||||||
about.md ← default
|
[Link text](pages/page2.md)
|
||||||
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.
|
This does not link to `page2.md`:
|
||||||
|
```
|
||||||
---
|
[Link text](page2.md)
|
||||||
|
|
||||||
## 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.
|
## Further reading
|
||||||
|
|
||||||
---
|
For further documentation, refer to:
|
||||||
|
|
||||||
|
- [docs/](docs/README.md): Documentation relevant to this repo
|
||||||
|
- [docs.benestad.net](https://docs.benestad.net/): Further help -- including an example of an MD-CMS site.
|
||||||
|
|
||||||
## Licence
|
## Licence
|
||||||
|
This software is © 2026 Kristian Benestad. Licensed under the [Apache License, Version 2.0](LICENSE).
|
||||||
Apache 2.0 — see [LICENCE]((https://www.apache.org/licenses/LICENSE-2.0)).
|
|
||||||
|
|
||||||
© Kristian Benestad
|
|
||||||
|
|
|
||||||
BIN
latest/linux/mdcms
Normal file
BIN
latest/linux/mdcms
Normal file
Binary file not shown.
BIN
latest/macos/mdcms
Normal file
BIN
latest/macos/mdcms
Normal file
Binary file not shown.
BIN
latest/windows/mdcms.exe
Normal file
BIN
latest/windows/mdcms.exe
Normal file
Binary file not shown.
Loading…
Reference in a new issue