From 3c27e86cf28c76c17e07be9630b476d496ae1b73 Mon Sep 17 00:00:00 2001 From: kbenestad Date: Sun, 17 May 2026 22:23:07 +0700 Subject: [PATCH] Upodated docs --- app/config.yml | 4 +- app/index.html | 4 +- docs/{release.md => dev-release.md} | 55 ++++++++---- docs/github-workflow.md | 130 ++++++++++++++++++++++++++++ docs/knownlimitations.md | 30 ------- docs/quickstart.md | 34 -------- docs/workflows.md | 52 +++++++++++ 7 files changed, 223 insertions(+), 86 deletions(-) rename docs/{release.md => dev-release.md} (65%) create mode 100644 docs/github-workflow.md delete mode 100644 docs/knownlimitations.md delete mode 100644 docs/quickstart.md create mode 100644 docs/workflows.md diff --git a/app/config.yml b/app/config.yml index 3583105..0da7820 100644 --- a/app/config.yml +++ b/app/config.yml @@ -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. diff --git a/app/index.html b/app/index.html index 40acf58..4d39c45 100644 --- a/app/index.html +++ b/app/index.html @@ -1,6 +1,6 @@ - + +``` + +**`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. diff --git a/docs/github-workflow.md b/docs/github-workflow.md new file mode 100644 index 0000000..5e26b3f --- /dev/null +++ b/docs/github-workflow.md @@ -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! \ No newline at end of file diff --git a/docs/knownlimitations.md b/docs/knownlimitations.md deleted file mode 100644 index b688f7f..0000000 --- a/docs/knownlimitations.md +++ /dev/null @@ -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. diff --git a/docs/quickstart.md b/docs/quickstart.md deleted file mode 100644 index a5e0047..0000000 --- a/docs/quickstart.md +++ /dev/null @@ -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. diff --git a/docs/workflows.md b/docs/workflows.md new file mode 100644 index 0000000..1fe8171 --- /dev/null +++ b/docs/workflows.md @@ -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. \ No newline at end of file