From ee3a967b86957727a3063e9a8ce56e658817988a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 21 May 2026 16:56:44 +0000
Subject: [PATCH] docs: add tabs and accordion reference to reference-pages.md

Documents all four block types (tab-underline, tab-filled,
accordion-underline, accordion-filled and their aliases) with
per-item key tables and worked examples, in the same style as
the existing callout/toc/posts-* sections.

https://claude.ai/code/session_01SFMh7PDxJjvvo5dYbCCFFs
---
 docs/reference-pages.md | 86 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/docs/reference-pages.md b/docs/reference-pages.md
index 6598ad9..287a336 100644
--- a/docs/reference-pages.md
+++ b/docs/reference-pages.md
@@ -167,6 +167,92 @@ paginate: yes                  # Pagination mode:
 
 ---
 
+### Tabs — `tab-underline`, `tab-filled`, `tab`
+
+A horizontal tab strip with a single visible content panel. The active tab is set with `default: selected`; if no item carries that value the first item is selected automatically.
+
+| Tag name | Appearance |
+|---|---|
+| `tab-underline` | Labels in a row; active tab marked with a 2 px underline in the accent colour. |
+| `tab` | Alias for `tab-underline`. |
+| `tab-filled` | Each label is a chip with a filled background; active chip inverts to the page background with an accent border. |
+
+The body of the block is YAML. It must start with `items:` followed by a list of item objects.
+
+````markdown
+```mdcms tab-underline
+items:
+  - title: npm
+    default: selected
+    content: |
+      ```bash
+      npm install mdcms
+      ```
+  - title: pnpm
+    content: |
+      ```bash
+      pnpm add mdcms
+      ```
+  - title: yarn
+    content: |
+      ```bash
+      yarn add mdcms
+      ```
+```
+````
+
+**Per-item keys:**
+
+| Key | Required | Notes |
+|---|---|---|
+| `title` | yes | Label on the tab button. Plain text only. |
+| `content` | yes | Tab panel body. Full Markdown, use `\|` for multi-line. |
+| `default` | no | `selected` — open on load. If no item is `selected`, the first item is used. |
+| `title-style` | no | Heading level for screen readers. One of `"#"` … `"######"` or `""` (default). Does not affect visual size. |
+
+---
+
+### Accordions — `accordion-underline`, `accordion-filled`, `accordion`
+
+Stacked collapsible items. Each item has a clickable header and a body that expands below it. Any number of items can be open simultaneously.
+
+| Tag name | Appearance |
+|---|---|
+| `accordion-underline` | Header separated from the content by a 2 px bar in the accent or nav colour; open content has a matching 1 px border on three sides. |
+| `accordion` | Alias for `accordion-underline`. |
+| `accordion-filled` | Closed header is a filled chip; when open the item becomes a single bordered card with the header fill at the top and the page background below. |
+
+````markdown
+```mdcms accordion
+items:
+  - title: What is MD-CMS?
+    default: open
+    content: |
+      A single-file browser renderer. No build pipeline, no compilation,
+      no server required.
+  - title: How do I install it?
+    content: |
+      Run `pip install mdcms` or download a binary from the GitHub releases page.
+  - title: Does it work offline?
+    content: |
+      Yes — run `mdcms fetch-deps` to bundle vendor assets locally, then enable
+      `pwa: yes` in `config.yml` for full offline support.
+```
+````
+
+**Per-item keys:**
+
+| Key | Required | Notes |
+|---|---|---|
+| `title` | yes | Header label. Plain text only. |
+| `content` | yes | Body shown when expanded. Full Markdown, use `\|` for multi-line. |
+| `default` | no | `open` — expanded on load. `closed` or omitted — collapsed. Multiple items may be `open`. |
+| `title-style` | no | Heading level for screen readers. One of `"#"` … `"######"` or `""` (default). Does not affect visual size. |
+
+**How the colour adapts to themes:** The bar/border colour and the chip fill are derived automatically from the active theme. On themes where the sidebar background is visually distinct from the page (dark nav on a light page, or a coloured nav), the components use the nav colour as their fill. On subtle themes where sidebar and page backgrounds are near-identical, the accent colour is used instead. No per-theme config is needed.
+
+---
+
 ## Markdown features
 
 Standard CommonMark plus GFM (GitHub-flavoured) extensions: