Add full reference doc for page frontmatter and mdcms tags

Covers all frontmatter fields, all mdcms code-block tag types (callout-*, toc, posts-created-*), tag options, raw HTML behaviour, and a full example page. https://claude.ai/code/session_01UP8Wo2CKPNhvvTkzX48CWF
2026-06-18 07:24:31 +00:00 · 2026-05-18 09:17:24 +00:00 · 2026-05-18 09:17:24 +00:00 · f9f3b9b81b
commit f9f3b9b81b
parent 74681670d7
1 changed files with 237 additions and 0 deletions
--- a/docs/reference-pages.md
+++ b/docs/reference-pages.md
@ -0,0 +1,237 @@
+# Page reference — frontmatter and mdcms tags
+
+All keys you can use inside a markdown page in `pages/` or `posts/`.
+
+A page has two parts:
+
+```markdown
+---
+# Frontmatter (YAML, optional except for title)
+title: My Page
+---
+
+Markdown body goes here.
+
+```mdcms
+toc
+```
+
+Regular markdown, plus mdcms code blocks for callouts, table of contents, post lists.
+```
+
+---
+
+## Frontmatter
+
+The YAML block delimited by `---` at the top of the file. Read by `mdcms build` to populate `nav.yml` and `search.json`, and by `index.html` at runtime to set the page title, dates, and meta tags.
+
+```yaml
+---
+title: Page Title              # REQUIRED. Browser tab title, nav label, h1 fallback.
+                               # Without this, the page is skipped from nav.yml.
+
+sort: 100                      # Position in the nav within its section. Lower = higher.
+                               # Default: 100. Tiebreaker is filename.
+
+section-id: guides             # Assigns this page to a section. Must match (or auto-create)
+                               # a code: in nav.yml. Omit to leave unsectioned.
+
+draft: true                    # Excludes the page from nav.yml AND search.json.
+                               # Default: false.
+
+author: Jane Doe               # Shown in the meta line under the page title (pages with author or created).
+
+created: 2026-05-18 14:30      # Publish date. Format: YYYY-MM-DD or YYYY-MM-DD HH:MM.
+                               # Required for posts to appear in posts-* tag listings.
+                               # Used as the sort key in chronological/reverse-chronological lists.
+
+modified: 2026-05-19 09:15     # Last-modified date. Shown next to created date if set.
+
+description: Short summary     # Used for the <meta name="description"> tag.
+                               # Falls back to config.yml sitedescription if omitted.
+
+keywords: foo, bar, baz        # Comma-separated. Indexed in search.json.
+
+language: en                   # BCP 47 code. Sets the <html lang=""> attribute when this page is loaded.
+                               # Doesn't filter pages — that's what categories are for.
+---
+```
+
+**Category variants** are not a frontmatter field — they are encoded in the filename. `about.nb.md` is the Norwegian variant of `about.md`, provided `nb` is declared in `config.yml` under `categories:`.
+
+---
+
+## mdcms code blocks
+
+Fenced blocks with the `mdcms` language tag are intercepted by the renderer and replaced with dynamic HTML. The tag name goes either on the fence line or on the first line of the block:
+
+````markdown
+```mdcms callout-info
+title: Heads up
+This is the body.
+```
+````
+
+…is equivalent to:
+
+````markdown
+```mdcms
+callout-info
+title: Heads up
+This is the body.
+```
+````
+
+Inside the block, lines matching `key: value` are parsed as options. The first non-matching line begins the body.
+
+---
+
+### Callout tags — `callout-info`, `callout-warning`, `callout-success`, `callout-error`
+
+A bordered, tinted box for notes, warnings, success messages, errors. Colour and icon come from `theme.yml` (`callouts:` block); fall back to built-in defaults.
+
+````markdown
+```mdcms callout-info
+title: Note                    # Optional. Bold title row with icon. Omit for a body-only callout.
+icon: lightbulb                # Optional. Override the default icon. Use an SVG name from assets/icons/.
+message: aitranslation         # Optional. Resolves title + body from config.yml callouts: block.
+                               # Takes precedence over inline title/body.
+
+Body text supports **full markdown** — bold, *italics*, `code`,
+[links](https://example.com), lists, etc.
+
+- item one
+- item two
+```
+````
+
+**Behaviour:**
+- Type comes from the tag name suffix (`info`/`warning`/`success`/`error`).
+- `message: <key>` looks up the named block in `config.yml`. When matched, the message's title and body override any inline values. The message's `type:` also overrides the tag type.
+- For multi-language messages, the renderer picks the entry for the active category, then the default category, then the first key.
+
+---
+
+### Table of contents — `toc`
+
+Renders a section-grouped, sorted list of all visible non-draft pages in the active category. The page containing the tag is excluded.
+
+````markdown
+```mdcms
+toc
+```
+````
+
+No options. Output is grouped by nav section in section sort order; pages within each section follow their own `sort:`.
+
+---
+
+### Post listings — `posts-created-*`
+
+Generate a chronologically sorted list of posts (files in `posts/`). Requires each post to have a `created:` value in frontmatter.
+
+**Reliable variants** (others are broken — do not use):
+
+```
+posts-created-chronological-byyearmonth
+posts-created-reversechronological
+```
+
+The grammar:
+
+```
+posts-created-<order>[-<modifier>]
+  order:    chronological | reversechronological
+  modifier: byyear | byyearmonth | lastyear | lastmonth   (optional)
+```
+
+- `byyear` / `byyearmonth` — group output by year, or by year-and-month.
+- `lastyear` / `lastmonth` — filter to posts from the last 365/30 days.
+- No modifier — flat list of all posts.
+
+````markdown
+```mdcms
+posts-created-reversechronological
+limit: 10                      # Max number of posts shown. Default: all.
+                               # When paginate: yes, this is the page size (batch size).
+
+paginate: yes                  # Pagination mode:
+                               # yes   — show a "load more" button after batchSize posts.
+                               # none  — show only the first <limit> posts, no pagination.
+                               # no    — show all posts at once (default).
+```
+````
+
+**Category filtering:** When `categories-use: yes`, the listing automatically filters to the active category.
+
+---
+
+## Markdown features
+
+Standard CommonMark plus GFM (GitHub-flavoured) extensions:
+
+- Tables
+- Strikethrough (`~~text~~`)
+- Task lists (`- [ ]` / `- [x]`)
+- Fenced code blocks with syntax language hints (`` ```python ``)
+- Autolinks
+
+**Raw HTML** passes through to the DOM. You can embed HTML directly:
+
+```markdown
+<meta http-equiv="refresh" content="0; url=docs/">
+```
+
+**Scripts injected via `<script>` tags in markdown do not execute** — the renderer uses `innerHTML`, which browsers block from running script tags. Use `<meta http-equiv="refresh">` for redirects.
+
+**Links to other pages** can use either:
+
+```markdown
+[Docs](pages/docs.md)          # Internal link — rewritten to a client-side route.
+[External](https://example.com)  # External — opens in new tab automatically.
+```
+
+---
+
+## Full example
+
+````markdown
+---
+title: Quick Start
+sort: 100
+section-id: getting-started
+author: Jane Doe
+created: 2026-05-18 14:30
+description: How to install and run MD-CMS in five minutes.
+keywords: install, setup, quickstart
+---
+
+# Quick start
+
+Welcome. This page walks you through installing MD-CMS.
+
+```mdcms callout-info
+title: Before you begin
+Make sure you have Python 3.9 or newer.
+```
+
+## Table of contents
+
+```mdcms
+toc
+```
+
+## Recent posts
+
+```mdcms
+posts-created-reversechronological
+limit: 5
+paginate: yes
+```
+
+## Translation notice
+
+```mdcms callout-warning
+message: aitranslation
+```
+````