diff --git a/README.md b/README.md index 307b308..f73e3fe 100644 --- a/README.md +++ b/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). diff --git a/latest/linux/mdcms b/latest/linux/mdcms new file mode 100644 index 0000000..7d8ca84 Binary files /dev/null and b/latest/linux/mdcms differ diff --git a/latest/macos/mdcms b/latest/macos/mdcms new file mode 100644 index 0000000..4617c8a Binary files /dev/null and b/latest/macos/mdcms differ diff --git a/latest/windows/mdcms.exe b/latest/windows/mdcms.exe new file mode 100644 index 0000000..c8df349 Binary files /dev/null and b/latest/windows/mdcms.exe differ