Publishing Kit

1) Layout & conventions

docs/
├─ wiki/ # All wiki pages, one file per page
│ ├─ Home.md
│ ├─ Getting-Started.md
│ ├─ ... (all the others, including _Sidebar.md, _Footer.md)
│ └─ Publishing-Kit.md
├─ tools/
│ ├─ export_wiki.sh # builds zip, single-file md/txt, checksums
│ ├─ link_audit.py # verifies [[WikiLink]] targets exist
│ └─ mermaid_check.py # light lint: labels quoted, no linebreaks
└─ release/
 └─ (artifacts get written here)

2) Tooling (install once)

sudo apt update
sudo apt install -y git python3 python3-venv zip coreutils
# Optional: for mkdocs site builds
sudo apt install -y python3-pip
python3 -m pip install --user mkdocs mkdocs-material
# Optional: Mermaid CLI for SVG rendering
# npm install -g @mermaid-js/mermaid-cli

3) Export script (zip + single files + checksums)

#!/usr/bin/env bash
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
WIKI="$ROOT/wiki"
OUT="$ROOT/../release"
DATE="${1:-$(date +%F)}"
NAME="HueyOS-wiki-$DATE"
mkdir -p "$OUT"
SINGLE_MD="$OUT/${NAME}_SINGLE.md"
SINGLE_TXT="$OUT/${NAME}_SINGLE.txt"
ZIP="$OUT/${NAME}.zip"
SUMS="$OUT/SHA256SUMS.txt"
# concat — keep a page delimiter for readability
: > "$SINGLE_MD"
: > "$SINGLE_TXT"
for f in $(ls "$WIKI"/*.md | sort); do
 bn="$(basename "$f")"
 {
 echo "<!-- $bn -->"
 cat "$f"
 echo
 } >> "$SINGLE_MD"
 {
 echo "==== $bn ===="
 cat "$f"
 echo
 } >> "$SINGLE_TXT"
done
# zip the wiki directory (relative paths)
(cd "$ROOT" && zip -r "$ZIP" "wiki")
# checksums
( cd "$OUT" && rm -f "$SUMS" && sha256sum "$(basename "$ZIP")" "$(basename "$SINGLE_MD")" "$(basename "$SINGLE_TXT")" > "$SUMS" )
echo "Wrote:"
printf " - %s\n - %s\n - %s\n - %s\n" "$ZIP" "$SINGLE_MD" "$SINGLE_TXT" "$SUMS"

chmod +x docs/tools/export_wiki.sh

docs/tools/export_wiki.sh # uses today's date
# or
docs/tools/export_wiki.sh 2025年10月31日

4) Link audit (catch missing [[...]] targets)

#!/usr/bin/env python3
import pathlib, re, sys
wiki = pathlib.Path(__file__).resolve().parents[1] / "wiki"
pages = {p.name for p in wiki.glob("*.md")}
missing = {}
link_pat = re.compile(r"\[\[([^\]]+)\]\]")
def page_target(t):
 if "|" in t: t = t.split("|",1)[0]
 t = t.split("#",1)[0]
 return t + ".md"
for p in sorted(wiki.glob("*.md")):
 text = p.read_text(encoding="utf-8")
 miss = []
 for m in link_pat.finditer(text):
 target = page_target(m.group(1))
 if target not in pages:
 miss.append(target)
 if miss:
 missing[p.name] = sorted(set(miss))
if missing:
 print("Missing wiki targets:")
 for k,v in missing.items():
 print(f"- {k}:")
 for t in v:
 print(f" * {t}")
 sys.exit(1)
else:
 print("OK — all [[...]] links resolve.")

python3 docs/tools/link_audit.py

5) Mermaid lint (quote labels, no linebreaks)

#!/usr/bin/env python3
import pathlib, re, sys
wiki = pathlib.Path(__file__).resolve().parents[1] / "wiki"
bad = []
mermaid = re.compile(r"```mermaid(.*?)```", re.S)
def labels_ok(block: str) -> bool:
 # All [Label] occurrences should be ["Label"]
 for m in re.finditer(r"\[[^\]]+\]", block):
 if not m.group(0).startswith('["'):
 return False
 # No explicit newline escape or <br/> inside labels
 if "\\n" in block or "<br" in block.lower():
 return False
 return True
for p in sorted(wiki.glob("*.md")):
 text = p.read_text(encoding="utf-8")
 for m in mermaid.finditer(text):
 if not labels_ok(m.group(1)):
 bad.append(p.name)
if bad:
 print("Mermaid blocks need fixing in:")
 for name in sorted(set(bad)):
 print(f"- {name}")
 sys.exit(1)
else:
 print("OK — Mermaid blocks pass basic checks.")

python3 docs/tools/mermaid_check.py

6) Publish to GitHub Wiki

# variables
REPO_SSH="git@github.com:<org-or-user>/<repo>.wiki.git"
# clone wiki repo (or pull if it exists)
rm -rf /tmp/huey-wiki
git clone "$REPO_SSH" /tmp/huey-wiki
# copy pages in
rsync -a --delete docs/wiki/ /tmp/huey-wiki/
# sanity checks before push
python3 docs/tools/link_audit.py
python3 docs/tools/mermaid_check.py
# commit + push
cd /tmp/huey-wiki
git add -A
git commit -m "docs(wiki): publish $(date +%F) — HueyOS"
git push

7) Optional: build a docs site (mkdocs)

site_name: Monkey-Head-Project (HueyOS) Wiki
theme:
 name: material
nav:
 - Home: docs/wiki/Home.md
 - Getting Started: docs/wiki/Getting-Started.md
 - Architecture: docs/wiki/Architecture.md
 - Hardware: docs/wiki/Hardware.md
 - Software Stack: docs/wiki/Software-Stack.md
 - Build Guides:
 - Index: docs/wiki/Build-Guides.md
 - Kernel 6.17.x: docs/wiki/Kernel-617x-Guide.md
 - LLM Setup: docs/wiki/LLM-Setup-AMD-or-CPU.md
 - Portal polish: docs/wiki/Portal-Polish-iMac5K.md
 - Governance: docs/wiki/Governance-and-Constitution.md
 - Memory: docs/wiki/Memory-and-Data-Model.md
 - Ops:
 - Networking & Services: docs/wiki/Networking-and-Services.md
 - Remote Access: docs/wiki/Remote-Access-VNC-SSH.md
 - Security & Operations: docs/wiki/Security-and-Operations.md
 - Action Plan (Oct 31, 2025): docs/wiki/Action-Plan-Oct-31-2025.md
 - Troubleshooting & FAQ: docs/wiki/Troubleshooting-and-FAQ.md
 - Publishing Kit: docs/wiki/Publishing-Kit.md

python3 -m pip install --user mkdocs mkdocs-material
mkdocs serve # http://127.0.0.1:8000
mkdocs build # outputs to site/

8) Makefile helpers

DATE ?= $(shell date +%F)
.PHONY: docs-audit docs-export docs-publish
docs-audit:
\tpython3 docs/tools/link_audit.py
\tpython3 docs/tools/mermaid_check.py
docs-export:
\tdocs/tools/export_wiki.sh $(DATE)
docs-publish: docs-audit docs-export
\t@echo "Ready to publish artifacts under release/"

make docs-audit
make docs-export DATE=2025年10月31日

9) CI (GitHub Actions) — publish on tag

name: Wiki Publish
on:
 push:
 tags:
 - "docs-*"
jobs:
 publish:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 with:
 fetch-depth: 0
 - name: Setup Python
 uses: actions/setup-python@v5
 with:
 python-version: "3.x"
 - name: Audit links & mermaid
 run: |
 python3 docs/tools/link_audit.py
 python3 docs/tools/mermaid_check.py
 - name: Export wiki
 run: docs/tools/export_wiki.sh ${GITHUB_REF_NAME#docs-}
 - name: Upload artifacts
 uses: actions/upload-artifact@v4
 with:
 name: wiki-${{ github.ref_name }}
 path: release/*

git tag docs-2025年10月31日
git push origin docs-2025年10月31日

10) Release checklist

Troubleshooting

License notes

Quick start (one-liner)

python3 docs/tools/link_audit.py && \
python3 docs/tools/mermaid_check.py && \
docs/tools/export_wiki.sh $(date +%F)