@@ -36,7 +36,7 @@ Set `SKIP_PIP_INSTALL=1` to skip automatic pip install in managed environments.
 2. Auto-generate nav from `docs/` frontmatter (title, order, section) + wiki pages
 3. Write merged config to temporary `mkdocs-build.yml`
 4. Run `mkdocs build` against merged config
-5. Render `showcase.html` template with `data/showcase.yml` → `dist/index.html` (headless strips `<nav>` and adds `data-kb-headless="true"`)
+5. Wrap the raw HTML under `content:` in `data/showcase.yml` into `dist/index.html` (headless strips the `<nav>` between the Navigation markers and adds `data-kb-headless="true"`)
 6. Copy `showcase.css` → `dist/showcase.css` (`admin/` too, standalone only)
 7. Write the computed `pages` list into `apps[0].pages` of `kb-docs.json` (in place; only that key is touched)
 8. `--pack` only: verify headless rules and pack `kb-docs.tar.gz`
@@ -52,7 +52,7 @@ docs/              → Markdown source files with YAML frontmatter
 data/showcase.yml  → Showcase landing page content (CMS-editable)
 theme/main.html    → Jinja2 page template (branded, dark mode toggle)
 theme/style.css    → Pre-compiled Tailwind CSS (edit Tailwind source to regenerate)
-showcase.html      → Jinja2 template for showcase (rendered from data/showcase.yml)
+showcase.html      → legacy Jinja2 showcase template; NOT used by the build (content lives in data/showcase.yml)
 showcase.css       → Showcase page styles (copied to dist/ at build time)
 scripts/pack.py    → Primary build script (cross-platform Python)
 scripts/pack.sh    → Bash build script (Linux/CI alternative)
@@ -84,7 +84,7 @@ section: Optional Section Name
 - Admin panel at `/admin/` — loads Sveltia CMS from CDN
 - Backend: GitHub (configure `backend.repo` in `admin/config.yml`)
 - Collections: docs (folder), showcase (file), knowledge base metadata `kb-docs.json` (file)
-- Showcase content lives in `data/showcase.yml` — rendered via Jinja2 template at build time
+- Showcase content lives in `data/showcase.yml` as raw HTML (`content:` key) — wrapped into a full page at build time
 - CMS commits trigger CI build; no separate build step needed
 
 ## MkDocs Theme
 
@@ -33,23 +33,26 @@ You can also create pages through the CMS at `/admin/`.
 
 ## Adding a standalone HTML page
 
-Standalone HTML pages (like `showcase.html`) are copied into `dist/` by the build script — they live alongside the MkDocs output.
+Standalone HTML pages are copied into `dist/` by the build script — they live alongside the MkDocs output, next to the showcase landing page.
 
 **Step 1** — Create your HTML file at the repo root:
 
 ```
 knowledge-base-docs-example/
-├── showcase.html
+├── showcase.css
 └── calculator.html   ← new standalone page
 ```
 
-**Step 2** — In `scripts/pack.py`, add a copy line in the section that handles showcase assets:
+Give it `data-kb-headless="true"` on `<html>`, no `<base>`, and only relative
+`href`/`src` paths — the publish action checks every HTML file in `dist/`.
 
-```bash
-cp calculator.html dist/calculator.html
+**Step 2** — In `scripts/pack.py`, copy it next to the showcase in `render_showcase()`:
+
+```python
+shutil.copy2("calculator.html", "dist/calculator.html")
 ```
 
-**Step 3** — Link to it from any Markdown page using a root-relative path:
+**Step 3** — Link to it from any Markdown page using a relative path:
 
 ```markdown
 [Open the calculator](../calculator.html)
 
@@ -78,7 +78,7 @@ theme:
 
 ## Showcase landing page
 
-The landing page at `dist/index.html` is rendered from `data/showcase.yml` through a Jinja2 template (`showcase.html`). Edit the YAML file to change headings, feature cards, steps, and CTA buttons — or use the CMS at `/admin/` for a visual editor.
+The landing page at `dist/index.html` is the raw HTML stored under `content:` in `data/showcase.yml`, wrapped into a full page by the build script. Edit that HTML to change headings, feature cards, steps, and CTA buttons — or use the CMS at `/admin/` for a live-preview editor. Keep the `<!-- ── Navigation ── -->` … `<!-- ── /Navigation ── -->` markers around the `<nav>`: the headless build removes exactly that block.
 
 Styles live in `showcase.css`. Design tokens are at the top of the file.
 
 
@@ -1,6 +1,6 @@
 ---
 title: Test page
-order: 5
+order: 6
 section: Playground
 ---
 This is some testing page ... !
 
@@ -36,7 +36,7 @@
         {
           "title": "Test page",
           "path": "docs/test-page/index.html",
-          "order": 5,
+          "order": 6,
           "section": "Playground"
         }
       ]
 
@@ -49,6 +49,13 @@
 from pathlib import Path
 
 
+# Windows consoles default to a legacy code page that cannot encode the
+# progress glyphs printed below; force UTF-8 so a local build does not crash.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+
+
 # ── Knowledge base contract (contract/ARTIFACT.md in AbsaOSS/knowledge-base) ──
 MANIFEST = "kb-docs.json"
 ASSET_NAME = "kb-docs.tar.gz"
 
@@ -223,20 +223,46 @@ if [ ! -f dist/docs/index.html ]; then
 fi
 
 if [ "$HEADLESS" = true ]; then
-  echo "▶ Copying showcase (without nav) as entry point..."
-  $PYTHON - <<'PY'
-import re, pathlib
-html = pathlib.Path('showcase.html').read_text(encoding='utf-8')
-html = re.sub(r'<!-- ── Navigation ── -->\s*<nav[^>]*>.*?</nav>', '', html, flags=re.DOTALL)
-# The knowledge base verifies every HTML file carries the headless marker on <html>.
-html = re.sub(r'<html\b', '<html data-kb-headless="true"', html, count=1)
-pathlib.Path('dist/index.html').write_text(html, encoding='utf-8')
-PY
+  echo "▶ Rendering showcase (headless)..."
 else
-  echo "▶ Copying showcase as entry point..."
-  cp showcase.html dist/index.html
+  echo "▶ Rendering showcase..."
 fi
+# Same as render_showcase() in pack.py: the raw HTML under `content:` in
+# data/showcase.yml is wrapped into a full page; headless drops the <nav> block
+# between the Navigation markers and stamps the headless marker on <html>.
+HEADLESS=$HEADLESS $PYTHON - <<'PY'
+import os, pathlib, re, yaml
+headless = os.environ.get('HEADLESS') == 'true'
+data = yaml.safe_load(pathlib.Path('data/showcase.yml').read_text(encoding='utf-8')) or {}
+content = data.get('content', '')
+if not content:
+    print('  ⚠ data/showcase.yml has no content — skipping showcase render')
+    raise SystemExit(0)
+if headless:
+    content = re.sub(r'<!-- ── Navigation ── -->\s*<nav[^>]*>.*?</nav>\s*<!-- ── /Navigation ── -->',
+                     '', content, flags=re.DOTALL)
+attrs = ' data-kb-headless="true"' if headless else ''
+html = f"""<!DOCTYPE html>
+<html lang="en"{attrs}>
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Showcase</title>
+  <link rel="stylesheet" href="docs/style.css" />
+  <link rel="stylesheet" href="showcase.css" />
+</head>
+<body>
+{content}
+</body>
+</html>"""
+pathlib.Path('dist/index.html').write_text(html, encoding='utf-8')
+PY
 [ -f showcase.css ] && cp showcase.css dist/showcase.css
+# The CMS is part of the standalone site only; its pages would fail the
+# knowledge base's headless verification.
+if [ "$HEADLESS" != true ] && [ -d admin ]; then
+  cp -r admin dist/admin
+fi
 
 echo "▶ Updating $MANIFEST pages manifest..."
 update_manifest_pages
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@`
`36`	`36`	`{`
`37`	`37`	`"title": "Test page",`
`38`	`38`	`"path": "docs/test-page/index.html",`
`39`		`- "order": 5,`
	`39`	`+ "order": 6,`
`40`	`40`	`"section": "Playground"`
`41`	`41`	`}`
`42`	`42`	`]`