kbenestad/mdcms
1
0
Fork 0
mirror of https://github.com/kbenestad/mdcms.git synced 2026-06-18 07:24:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Upodated docs

Browse source
This commit is contained in:
Kristian Benestad 2026-05-17 22:23:07 +07:00
parent 56c22f075d
commit 3c27e86cf2
7 changed files with 223 additions and 86 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
app/config.yml
View file

@ -1,5 +1,5 @@
# mdcms v0.3 | DO NOT REMOVE THIS COMMENT
# MD-CMS v0.3 — Site configuration
# Minimum supported version: mdcms v0.3.2 | DO NOT REMOVE THIS COMMENT
# MD-CMS v0.3.2 — Site configuration
#
# Only `sitename` and `navigation` are required. Uncomment and edit the rest
# as needed. See https://kbenestad.codeberg.page/md-cms for the full reference.

4
app/index.html
View file

@ -1,6 +1,6 @@
<!-- mdcms v0.3 | DO NOT REMOVE THIS COMMENT -->
<!-- Minimum supported version: mdcms v0.3.8 | DO NOT REMOVE THIS COMMENT -->
<!--
MD-CMS v0.3 — Renderer
MD-CMS v0.3.8 — Renderer
Copyright 2026 Kristian Benestad | kbenestad.codeberg.page

55
docs/release.md → docs/dev-release.md
View file

@ -1,10 +1,10 @@
# Releasing a new version of mdcms
# Release workflow
This guide covers publishing a new mdcms release — producing binaries, a `.deb` package, and a GitHub release with all artifacts attached.
This document covers the automatic creation of release binaries of MD-CMS for Linux, macOS and Windows. This document is relevant for you who want to continue developing MD-CMS on your own.
## Prerequisites
- Push access to `kbenestad/mdcms` on GitHub
- Push access to your GitHub release repository
- GitHub Actions enabled on the repository (it is by default on new repos)
## One-time GitHub setup
@ -14,7 +14,7 @@ This guide covers publishing a new mdcms release — producing binaries, a `.deb
The release workflow creates a GitHub release using the built-in `GITHUB_TOKEN`. You need to confirm it has write access:
1. Go to your repository on GitHub
2. **Settings → Actions → General**
2. Go to **Settings → Actions → General**
3. Scroll to **Workflow permissions**
4. Select **Read and write permissions**
5. Click **Save**
@ -24,47 +24,60 @@ That's the only setup required. No secrets, no tokens, no third-party services.
## The release checklist
### Update version number
Before tagging a release, update the version number in two places:
Before tagging a release, update the version number in at least places:
**`mdcms.py`** — find this line near the top and bump it:
```python
CLI_VERSION = "0.3.1"
CLI_VERSION = "0.3.8"
```
**`pyproject.toml`** — bump the matching line:
```toml
version = "0.3.1"
version = "0.3.8"
```
> **Site format version** — the markers in `app/config.yml` and `app/index.html` (`# mdcms v0.3`) are separate from the CLI version. Only update them if the site file format has a breaking change that requires users to re-download the template. Most releases do not touch these.
If you have made changes that affect the `index.html` and/or `config.yml`, update the minimum supported version comment at the top of each file:
**`app/index.html`** — bump the matching line:
```html
<!-- Minimum supported version: mdcms v0.3.8 | DO NOT REMOVE THIS COMMENT -->
```
**`app/config.yml`** — bump the matching line:
```yml
# Minimum supported version: mdcms v0.3.2 | DO NOT REMOVE THIS COMMENT
```
#### Commit locally
Commit the version bump:
```bash
git add mdcms.py pyproject.toml
git commit -m "Bump version to 0.3.1"
git commit -m "Bump version to 0.3.8"
git push origin main
```
#### Commit on the web
Save each file with a version bump notice: `"Bump version to 0.3.1"`.
Save each file with a version bump notice: `"Bump version to 0.3.8"`.
### Tagging the release
#### Locally
Push a version tag to trigger the workflow:
```bash
git tag v0.3.1
git push origin v0.3.1
git tag v0.3.8
git push origin v0.3.8
```
#### On the web
1. Go to your repository → Releases (right sidebar)
1. Click Draft a new release
1. Click Choose a tag → type v0.3.0 → click Create new tag: v0.3.0 on publish
1. Click Choose a tag → type v0.3.7 → click Create new tag: v0.3.8 on publish
1. Leave the target branch as main
1. Click Generate release notes
1. Click Publish release
The binaries will be generated by
#### Common
The tag must start with `v`. The workflow triggers immediately.
@ -93,11 +106,14 @@ A final job collects all artifacts and creates the GitHub release with auto-gene
If a job fails, the release is not created. Fix the issue, delete the tag, and re-push:
```bash
git tag -d v0.3.1
git push origin --delete v0.3.1
# fix the issue, then re-tag
git tag v0.3.1
git push origin v0.3.1
git tag -d v0.3.8
git push origin --delete v0.3.8
```
Fix the issue, then re-tag:
```bash
git tag v0.3.8
git push origin v0.3.8
```
## The finished release
@ -105,3 +121,6 @@ git push origin v0.3.1
Once all jobs pass, the release appears under **Releases** on the repository with:
- Auto-generated changelog (commits since the last tag)
- All four artifacts attached for download
## Follow-up
If you serve `latest` binaries from a standard URL, you also have to make sure to update these.

130
docs/github-workflow.md Normal file
View file

@ -0,0 +1,130 @@
# Automatic generation of `nav.yml` and `search.json`
This document covers
## Enable GitHub Actions
Before you can set up the automation workflow you need to ensure that it has write access:
1. Go to your repository on GitHub
2. Go to **Settings → Actions → General**
3. Scroll to **Workflow permissions**
4. Select **Read and write permissions**
5. Click **Save**
That's the only setup required. No secrets, no tokens, no third-party services.
## Enable workflow on single site
Create `.github/workflows/build.yml` in your repository.
Assuming that the MD-CMS site is hosted at the repository root, you just need to paste the following into `build.yml`
```bash
name: Build
on:
push:
branches:
- main
paths:
- "pages/**"
- "posts/**"
- "config.yml"
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install mdcms
run: pip install mdcms
- name: Build
run: mdcms build
- name: Commit updated files
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add nav.yml search.json
git diff --staged --quiet || git commit -m "Build: update nav.yml and search.json"
git push
```
If your MD-CMS instance is served from a directory within the repository (e.g., `docs`), you need to adjust the following paths accordingly:
```bash
paths:
- "[PATH TO SITE]/pages/**"
- "[PATH TO SITE]/posts/**"
- "[PATH TO SITE]/config.yml"
```
## Enable workflow on multisites
If you serve multiple MD-CMS instances from the same repository, you need to use a customised version of the script.
Create `.github/workflows/build.yml` in your repository.
Review the script below. It has been set up with four different directories (`DIRECTORY`, `DIRECTORY2`, `DIRECTORY3`, and `DIRECTORY4`). Change the paths to your own directories:
```bash
name: Build
on:
push:
branches:
- main
paths:
- "[DIRECTORY1]/pages/**"
- "[DIRECTORY1]/posts/**"
- "[DIRECTORY1]/config.yml"
- "[DIRECTORY2]/pages/**"
- "[DIRECTORY2]/posts/**"
- "[DIRECTORY2]/config.yml"
- "[DIRECTORY3]/pages/**"
- "[DIRECTORY3]/posts/**"
- "[DIRECTORY3]/config.yml"
- "[DIRECTORY4]/pages/**"
- "[DIRECTORY4]/posts/**"
- "[DIRECTORY4]/config.yml"
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install mdcms
run: pip install mdcms
- name: Build all sections
run: |
for section in [DIRECTORY1] [DIRECTORY2] [DIRECTORY3] [DIRECTORY4]; do
cd $section
mdcms build
cd ..
done
- name: Commit updated files
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add docs/nav.yml docs/search.json legal/nav.yml legal/search.json learning/nav.yml learning/search.json sysadmin/nav.yml sysadmin/search.json
git diff --staged --quiet || git commit -m "Build: update nav.yml and search.json"
git push
```
**IMPORTANT:** Please take note of the `run` part, where each directory is listed:
```bash
for section in [DIRECTORY1] [DIRECTORY2] [DIRECTORY3] [DIRECTORY4]; do
```
This is different from the single site workflow. If you move from single site to multisite you need to updated the entire script -- it is not sufficient to just list the paths!

30
docs/knownlimitations.md
View file

@ -1,30 +0,0 @@
# MD-CMS — Known limitations
MD-CMS is under active development.
## mdcms.py only targets `/website` directory inside a project directory
You can run `mdcms.py` from anywhere and define multiple projects. However, the current version excepts the website itself to live inside a `/website` directory inside your project directory.
In other words, you cannot keep the files in
- `/home/username/mdcmssites/site-1` and
- `/home/username/mdcmssites/site-2`
they must be in
- `/home/username/mdcmssites/site-1/website` and
- `/home/username/mdcmssites/site-2/website`.
## mdcms tags for posts
The tags that lists posts are broken. Currently, the only tags that reliably show posts are:
- `posts-datetime-chronological-byyearmonth`
- `posts-datetime-reversechronological`
To correctly show posts, use `datetime` in frontmatter.
The tag `created` is defined in the frontmatter as the created date of a file, but it is not used.
Use `datetime` to indicate the date and time a file was created, using the format `YYYY-MM-DD HH:MM` (e.g., `2026-01-14 13:35`).
Use `modified` using the format `YYYY-MM-DD HH:MM` (e.g., `2026-01-14 13:35`) to show users when a file was last updated.

34
docs/quickstart.md
View file

@ -1,34 +0,0 @@
# MD-CMS — Quickstart
A lightweight Markdown-based CMS. Content is written as plain Markdown with YAML frontmatter; configuration lives in `website/config.yml`; navigation and search are generated by `mdcms.py`.
## First run
1. Put content into `website/pages/` and `website/posts/`.
2. Edit `website/config.yml` with your site name and preferences.
3. From this directory, run `python3 mdcms.py`.
4. In the menu, pick option **7** to register the website path (point it at the `website/` folder).
5. Pick option **3** to build `nav.yml` and `search.json`.
6. Pick option **8** to start a local webserver and preview the site.
## File layout
```
mdcms.py
quickstart.md
website/
assets/
fonts/
images/
pages/
home.md
posts/
index.html
config.yml
nav.yml (generated)
search.json (generated)
```
## Licence
Apache 2.0. See [docs.benestad.net](https://docs.benestad.net) for documentation.

52
docs/workflows.md Normal file
View file

@ -0,0 +1,52 @@
# Setting up MD-CMS for your site
This document walks you through the installation of MD-CMS.
## Minimum install
The bare minimum required to run MD-CMS is to download the content in [**app/**](https://github.com/kbenestad/mdcms/tree/main/app) and upload the files and folders to any web-server.
## Recommended install
To properly use MD-CMS you need to download the CLI tool.
### Linux
To download MD-CMS for Linux, you need to run the appropriate command below in the terminal. Verify which version you have installed by running `mdcms --version`.
#### Debian and Debian-based distros (including Ubuntu)
The .deb package handles all installation details. To download and install, run:
```
curl -fsSLO https://raw.githubusercontent.com/kbenestad/mdcms/main/latest/linux/mdcms.deb && sudo dpkg -i mdcms.deb
```
#### All other Linux distros
For all other Linux distros, please run the following command in the terminal:
```
sudo curl -fsSL https://raw.githubusercontent.com/kbenestad/mdcms/main/latest/linux/mdcms -o /usr/local/bin/mdcms && sudo chmod +x /usr/local/bin/mdcms
```
This command fetches the latest binary, moves it to `/usr/local/bin/mdcms` and makes it executable in one go.
### MacOS
Open terminal and run this command to install `mdcms`:
```
sudo curl -fsSL https://raw.githubusercontent.com/kbenestad/mdcms/main/latest/macos/mdcms -o /usr/local/bin/mdcms && sudo chmod +x /usr/local/bin/mdcms
```
MacOS may block the binary on first run ("cannot be opened because the developer cannot be verified"). If so, run the following command:
```
sudo xattr -d com.apple.quarantine /usr/local/bin/mdcms
```
once to clear it. Verify which version you have installed by running `mdcms --version`.
### Windows
In Windows 10 or 11, open PowerShell and run the following command:
```
Invoke-WebRequest https://raw.githubusercontent.com/kbenestad/mdcms/main/latest/windows/mdcms.exe -OutFile "$env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\mdcms.exe"
```
Verify which version you have installed by running `mdcms --version`.
## Update
MD-CMS consists of two separate pieces of software: The CLI tool (which you run from the terminal) and the renderer (the index.html file, which the browser reads). To update the CLI, simply rerun the installation command and overwrite `mdcms`. To update the renderer, download the latest index.html and overwrite it in your sites.