Skip to content

Publishing Kit

Jump to bottom
Dylan L.R. Pollock edited this page Oct 26, 2025 · 1 revision

Publishing Kit

This page shows you how to package, audit, and publish the Monkey-Head-Project (HueyOS) wiki. It assumes a Debian 13 baseline, git installed, and that you either (a) publish to a GitHub Wiki (<repo>.wiki.git) or (b) a docs site (mkdocs). Everything here stays offline-first until the “push” step.

Outputs

  • wiki/*.md — per-page Markdown files (GitHub Wiki-ready)
  • HueyOS-wiki-YYYY-MM-DD.zip — zip archive
  • HueyOS-wiki-YYYY-MM-DD_SINGLE.md — single file
  • HueyOS-wiki-YYYY-MM-DD_SINGLE.txt — plaintext
  • SHA256SUMS.txt — checksums for integrity
  • (optional) site/ — static docs site (mkdocs)

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)

Wiki rules that keep GitHub happy

  • Mermaid labels must be quoted: Node["Text & (GPU1)"]
  • No line breaks inside Mermaid labels; one line per node
  • Prefer [[Page-Name|Alias]] links; anchors allowed ([[Page#section]])
  • Keep filenames ASCII; match the [[Page-Name]] exactly + .md

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)

Create docs/tools/export_wiki.sh:

#!/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"

Make it executable:

chmod +x docs/tools/export_wiki.sh

Run it:

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

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

Create docs/tools/link_audit.py:

#!/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.")

Run it:

python3 docs/tools/link_audit.py

5) Mermaid lint (quote labels, no linebreaks)

Create docs/tools/mermaid_check.py:

#!/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.")

Run it:

python3 docs/tools/mermaid_check.py

6) Publish to GitHub Wiki

GitHub Wikis are separate repos named <REPO>.wiki.git. You push Markdown files into the root.

# 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

Notes

  • _Sidebar.md and _Footer.md go in the root of the wiki repo.
  • Avoid non-ASCII filenames; GitHub treats page names as filenames.

7) Optional: build a docs site (mkdocs)

Create mkdocs.yml at repo root:

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

Build and preview:

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

8) Makefile helpers

Add to your top-level Makefile:

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/"

Usage:

make docs-audit
make docs-export DATE=2025-10-31

9) CI (GitHub Actions) — publish on tag

Create .github/workflows/wiki-publish.yml:

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/*

Push a tag to trigger:

git tag docs-2025-10-31
git push origin docs-2025-10-31

10) Release checklist

  • make docs-audit passes (no missing links; Mermaid clean)
  • make docs-export DATE=YYYY-MM-DD wrote zip/single/txt + checksums
  • Spot-check Home.md, Architecture.md diagrams render on GitHub
  • If using GitHub Wiki, pushed to <repo>.wiki.git and pages load
  • Archive artifacts into Storage Hub with date path
  • Record checksums release/SHA256SUMS.txt in your snapshot manifest

Troubleshooting

  • “Unable to render rich display / Parse error … got 'PS'” Label contains an & or parentheses without quotes. Fix with Node["A & B (GPU1)"].

  • Broken wiki link Ensure the target file exists as Page-Name.md. Anchors (#section) don’t create files—only the base page must exist.

  • CI fails on Mermaid The linter looks for [" at the start of each label token. If you intentionally use shapes like ([rounded]), still wrap text: A(["rounded"]).

License notes

  • Code in tools/scripts: GPL-3.0
  • Docs/Media: CC-BY-SA-4.0 Include the license headers if you copy these into other projects.

Quick start (one-liner)

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

That’s the whole publishing story: audit → export → (optional) site → push.

Clone this wiki locally