Skip to content

Singular Dream: GitHub Wiki Setup Guide

1. The Conceptual Model: "Shadow Repository"

You identified the core concept correctly: The GitHub Wiki is a completely separate Git repository associated with your project.

  • Main Repo: github.com/org/singular-dream.git (Source of Truth, PRs, Version Control)
  • Wiki Repo: github.com/org/singular-dream.wiki.git (Public Read-Only View)

The Problem

If you edit the Wiki directly in the browser, your documentation drifts apart from your code. You lose the ability to review changes in Pull Requests.

The Solution: "Docs as Code"

We keep the documentation inside the Main Monorepo (folder: documentation/) and use an Automated Bridge to sync it to the Wiki Repo on every merge to main.

graph LR
    Dev[Developer] -->|Commits| MainRepo[Main Repo (Source)]
    MainRepo -->|GitHub Action| Sync[Sync Script]
    Sync -->|Push| WikiRepo[Wiki Repo (Target)]
    WikiRepo -->|Read| Users[Stakeholders]

2. Directory Structure Strategy

GitHub Wiki creates pages based on Markdown files. It supports folders, but the navigation UI is flat by default. To make it "Cleanly Structured," we must enforce a navigation structure.

We transfer the documentation/ folder to the matching Wiki structure:

Main Repo Path Wiki Role
documentation/00_INDEX.md Home.md (The Landing Page)
documentation/_Sidebar.md _Sidebar.md (The Navigation Menu)
documentation/_Footer.md _Footer.md (Copyright/Links)
documentation/01_architecture/* 01_architecture/* (Nested Pages)

Important Rules

  1. Relative Links: All links must be relative (e.g., [Link](../folder/file.md)). Our current documentation already follows this standard.
  2. Images: Images must be committed to the Wiki repo (e.g., in an images/ folder) to be visible.

3. Setup Steps

Step 1: Initialize the Wiki

  1. Go to your GitHub Repository > Settings > General.
  2. Scroll to Features and check Wikis.
  3. Go to the Wiki tab.
  4. Create the first page (just type "Hello" and save) to initialize the underlying git repository.

Step 2: Clone both Repositories locally

Open your terminal:

# 1. Your existing monorepo is likely already cloned
cd singular-dream

# 2. Clone the Wiki repo into a temporary folder to inspect it
git clone https://github.com/YOUR_ORG/singular-dream.wiki.git wiki-temp

Step 3: Prepare the Sidebar

The _Sidebar.md file controls the right-hand menu on the Wiki. We should generate this from our 00_INDEX.md.

Create a file documentation/_Sidebar.md with content like:

- [Home](Home)
- **Architecture**
  - [Master Blueprint](01_architecture/blueprints/01_MASTER_BLUEPRINT)
  - [Domain Atlas](01_architecture/blueprints/03_DOMAIN_ATLAS)
- **Standards**
  - [Engineering Handbook](02_standards/process/02_ENGINEERING_HANDBOOK)

Step 4: The Sync Workflow (Automation)

Create a GitHub Action file in your main repo: .github/workflows/docs-sync.yml.

name: Sync to Wiki

on:
  push:
    branches: [main]
    paths:
      - "documentation/**"

jobs:
  sync-wiki:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Sync Docs to Wiki
        uses: newish34/github-wiki-publish-action@v1
        with:
          username: ${{ github.actor }}
          token: ${{ secrets.GITHUB_TOKEN }}
          wiki-src-folder: "documentation"
          wiki-dest-folder: "."
          # Map INDEX to Home
          replace-homepage: "00_INDEX.md"

4. Manual "One-Time" Push (Proof of Concept)

If you want to do this manually right now to see the result:

# 1. Clone Wiki
git clone https://github.com/YOUR_ORG/singular-dream.wiki.git ../singular-dream-wiki

# 2. Clean Wiki (Careful!)
rm -rf ../singular-dream-wiki/*

# 3. Copy Docs
cp -R documentation/* ../singular-dream-wiki/

# 4. Rename Index to Home
mv ../singular-dream-wiki/00_INDEX.md ../singular-dream-wiki/Home.md

# 5. Push
cd ../singular-dream-wiki
git add .
git commit -m "Manual sync of documentation"
git push

Your Wiki is now live and structured exactly like your standard folders.

Version History

Version Date Author Change
0.1.0 2026-01-26 Antigravity Initial Audit & Metadata Injection