kbenestad/mdcms
1
0
Fork 0
mirror of https://github.com/kbenestad/mdcms.git synced 2026-06-18 15:24:32 +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 # Minimum supported version: mdcms v0.3.2 | DO NOT REMOVE THIS COMMENT
# MD-CMS v0.3 — Site configuration # MD-CMS v0.3.2 — Site configuration
# #
# Only `sitename` and `navigation` are required. Uncomment and edit the rest # Only `sitename` and `navigation` are required. Uncomment and edit the rest
# as needed. See https://kbenestad.codeberg.page/md-cms for the full reference. # 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 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 ## 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) - GitHub Actions enabled on the repository (it is by default on new repos)
## One-time GitHub setup ## 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: 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 1. Go to your repository on GitHub
2. **Settings → Actions → General** 2. Go to **Settings → Actions → General**
3. Scroll to **Workflow permissions** 3. Scroll to **Workflow permissions**
4. Select **Read and write permissions** 4. Select **Read and write permissions**
5. Click **Save** 5. Click **Save**
@ -24,47 +24,60 @@ That's the only setup required. No secrets, no tokens, no third-party services.
## The release checklist ## The release checklist
### Update version number ### 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: **`mdcms.py`** — find this line near the top and bump it:
```python ```python
CLI_VERSION = "0.3.1" CLI_VERSION = "0.3.8"
``` ```
**`pyproject.toml`** — bump the matching line: **`pyproject.toml`** — bump the matching line:
```toml ```toml
version = "0.3.1" version = "0.3.8"
```
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
``` ```
> **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.
#### Commit locally #### Commit locally
Commit the version bump: Commit the version bump:
```bash ```bash
git add mdcms.py pyproject.toml 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 git push origin main
``` ```
#### Commit on the web #### 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 ### Tagging the release
#### Locally #### Locally
Push a version tag to trigger the workflow: Push a version tag to trigger the workflow:
```bash ```bash
git tag v0.3.1 git tag v0.3.8
git push origin v0.3.1 git push origin v0.3.8
``` ```
#### On the web #### On the web
1. Go to your repository → Releases (right sidebar) 1. Go to your repository → Releases (right sidebar)
1. Click Draft a new release 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. Leave the target branch as main
1. Click Generate release notes 1. Click Generate release notes
1. Click Publish release 1. Click Publish release
The binaries will be generated by
#### Common #### Common
The tag must start with `v`. The workflow triggers immediately. 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: If a job fails, the release is not created. Fix the issue, delete the tag, and re-push:
```bash ```bash
git tag -d v0.3.1 git tag -d v0.3.8
git push origin --delete v0.3.1 git push origin --delete v0.3.8
# fix the issue, then re-tag ```
git tag v0.3.1
git push origin v0.3.1 Fix the issue, then re-tag:
```bash
git tag v0.3.8
git push origin v0.3.8
``` ```
## The finished release ## 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: Once all jobs pass, the release appears under **Releases** on the repository with:
- Auto-generated changelog (commits since the last tag) - Auto-generated changelog (commits since the last tag)
- All four artifacts attached for download - 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.