GitHub wiki for research content

Research Question

What is the best approach for publishing completed research items from Research/completed/ into the GitHub wiki, and what tooling is needed to keep it current and readable?

Findings

Executive Summary

The GitHub wiki is a separate, flat git repository ({repo}.wiki.git) that can be cloned and pushed by any Actions workflow with contents: write permission using the built-in GITHUB_TOKEN — no PAT required. A full-rebuild approach (delete all pages, regenerate from Research/completed/ on each push) is correct for this repository's volume and eliminates incremental state complexity. A Python script strips YAML front-matter, writes one wiki page per completed item, and generates Home.md (date-sorted index) and _Sidebar.md (tag navigation). The workflow triggers on any push to main that touches Research/completed/**, and also supports workflow_dispatch for manual runs. The wiki must be enabled once in repository Settings.

Key Findings

1. The GitHub wiki is a distinct git repo. Every repository's wiki lives at github.com. It can be cloned and pushed like any git repository. actions/checkout@v4 supports a repository: parameter that accepts ${{ github.repository }}.wiki, making checkout straightforward.

2. GITHUB_TOKEN is sufficient — no PAT needed. Actions workflows with permissions: contents: write can push to the wiki repo of the same repository using ${{ secrets.GITHUB_TOKEN }}. No additional secrets are required.

3. Pages are flat — no subdirectories. The wiki URL structure is /{owner}/{repo}/wiki/{Page-Name}. Filenames map directly to page names; slashes in filenames are not supported. The constraint is acceptable for research items because each item already has a unique date-prefixed filename.

4. Three special pages control structure. Home.md is the landing page for the Wiki tab. _Sidebar.md renders a persistent sidebar on every page. _Footer.md renders a persistent footer. These are the only navigation primitives the GitHub wiki natively supports.

5. Internal wiki links use [[Page Name]] syntax. Cross-references between wiki pages use double-bracket notation: [[2026-02-28-ai-strategy]] or [[2026-02-28-ai-strategy|AI Strategy]] for aliased display text.

6. Full rebuild is simpler than incremental. The wiki repo is wiped and rebuilt on every workflow run. At the current volume (tens of items), this takes under a second. It eliminates the need to track renames, deletions, or status changes — the completed directory is the authoritative source.

7. YAML front-matter must be stripped. Wiki readers should see the research content directly, not raw YAML. Stripping the front-matter block (everything between the opening and closing ---) and using the parsed metadata for the index and sidebar is the correct approach.

8. The wiki must be enabled before the first push. GitHub wikis are disabled by default on new repositories. The owner must enable it once via Settings → Features → Wikis. After that, the automated workflow maintains it.

Assumptions

• Assumption: The davidamitchell/Research wiki is currently empty or does not exist. Justification: No wiki content has been referenced in any session log or PROGRESS.md entry; the wiki tab was not mentioned as populated.
• Assumption: PyYAML (already a project dependency) is sufficient for front-matter parsing in the Actions runner. Justification: PyYAML>=6.0 is listed in pyproject.toml dependencies.
• Assumption: The publish step can run with Python installed from actions/setup-python@v5 using the project's existing pip install -e . pattern. Justification: This is the pattern used by ci.yml and fetch-transcript.yml.

Analysis

Two pipeline designs were considered:

Option A — Full rebuild: On each trigger, checkout the wiki repo, delete all .md files, regenerate all pages from Research/completed/, push. Simple, stateless, correct by construction. Handles renames and deletions automatically.

Option B — Incremental: Track which research items have been published (by hash or mtime), only push changed pages. More complex, requires state, and the benefit (faster push) is negligible at the current volume.

Full rebuild (Option A) was selected. The research corpus is small (currently ~10 completed items) and grows slowly. Rebuilding the entire wiki takes milliseconds. Eliminating incremental state complexity is worth more than the marginal speed gain.

For navigation, two structures were designed:

• Home.md: date-sorted table of all completed items with title, date, tags, and a wiki link
• _Sidebar.md: tag-grouped navigation list

Both are regenerated on every rebuild.

Risks, Gaps, and Uncertainties

• Wiki must be enabled manually first. If the wiki has never been enabled, the first git push to the wiki URL will fail. The workflow cannot enable it programmatically. The owner must click Settings → Features → Wikis once.
• Rate limits on wiki pushes. The GitHub API rate limit applies to authenticated pushes. At one push per main branch commit, this is not a concern in practice.
• Wiki page names and GitHub's canonicalisation. GitHub normalises wiki page names (spaces become hyphens, etc.). The date-prefixed filename convention (2026-02-27-...) is safe — all characters are URL-safe.

Open Questions

• Should Research/in-progress/ items also be published to the wiki with a "work in progress" label? (Out of scope for this item — start with completed only.)
• Should research items with output: [knowledge] be tagged differently from those with output: [tool]? (Possible future enhancement.)

sources

• [x] GitHub Docs — Wikis
• [x] GitHub Actions — checkout wiki repo pattern (common community pattern using actions/checkout with wiki URL)
• [x] GitHub Docs — GITHUB_TOKEN permissions
• [x] Community examples: auto-wiki patterns using actions/checkout with wiki repo URL