quaex

GitHub Wiki Setup Guide (Internal)

This guide explains how to enable and maintain the internal engineering wiki for the Quaex / Parth prototype.

1. Enable Wiki Feature

1. Navigate to the repository Settings → General.
2. Under “Features” ensure “Wikis” is checked.
3. Keep the repository private (required for proprietary material).

2. Local Authoring Flow

All source-of-truth wiki pages live in the wiki/ directory in the main repository:

wiki/
  Home.md
  Architecture-Overview.md
  Development-Environment.md
  Security-Overview.md
  Release-Process.md
  Runbook.md
  Glossary.md

3. Sync Mechanism

A GitHub Action workflow (sync-wiki.yml) mirrors wiki/ contents to the GitHub wiki repository (<repo>.wiki.git). Triggers:

• Push to main changing files under wiki/
• Manual dispatch via Actions tab (“Sync Wiki”)

4. Manual Sync (Local)

You can run:

./scripts/sync_wiki.sh

Requires either an environment variable GITHUB_TOKEN (PAT with repo scope) or interactive credential if you have push rights.

5. Adding New Pages

1. Create new wiki/Your-Page-Name.md.
2. Link it from wiki/Home.md using [[Your-Page-Name]].
3. Commit & push to main.
4. Workflow sync runs automatically.

6. Content Guidelines

| Rule | Rationale | |——|———–| | No secrets or keys | Repo may be cloned to wider internal teams | | Keep pages < 200 lines | Encourage focus & maintainability | | Use tables for procedures | Faster operational scanning | | Stamp Last Updated date | Track staleness |

7. Recovery / Resync

If wiki repo diverges unexpectedly:

1. Delete remote wiki contents via cloning <repo>.wiki.git manually.
2. Run a fresh sync (workflow_dispatch).
3. Confirm commit history contains only sync entries.

8. Future Enhancements

• Automatic TOC generation
• Link validation lint step
• Diagram as code (Mermaid) rendering pipeline

---

Last Updated: 2025-09-25