mirror of
https://github.com/kbenestad/mdcms.git
synced 2026-06-18 07:24:31 +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
|
||||
|
||||
> 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.
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
1) Download the latest [release](https://github.com/kbenestad/mdcms/releases) for your
|
||||
---
|
||||
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:
|
||||
|
||||
**`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
|
||||
- **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
|
||||
**Standalone binary**
|
||||
|
||||
---
|
||||
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
|
||||
|
||||
```
|
||||
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/
|
||||
[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
|
||||
...
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
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:
|
||||
```
|
||||
about.md ← default
|
||||
about.en-gb.md ← British English variant
|
||||
about.nb.md ← Norwegian variant
|
||||
[Link text](pages/page2.md)
|
||||
```
|
||||
|
||||
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
|
||||
This does not link to `page2.md`:
|
||||
```
|
||||
[Link text](page2.md)
|
||||
```
|
||||
````
|
||||
|
||||
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
|
||||
|
||||
Apache 2.0 — see [LICENCE]((https://www.apache.org/licenses/LICENSE-2.0)).
|
||||
|
||||
© Kristian Benestad
|
||||
This software is © 2026 Kristian Benestad. Licensed under the [Apache License, Version 2.0](LICENSE).
|
||||
|
|
|
|||
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