github-wiki-flat

GitHub Wiki Is Flat

Category: GitHub Time Saved: 1-2 hours debugging broken links Battle-tested: Yes — wiki publishing automation

---

The Problem

You organize your wiki source files in a nice folder structure:

wiki/
  getting-started/
    installation.md
    configuration.md
  api/
    endpoints.md
    authentication.md

You push to GitHub Wiki. All your internal links break. Pages appear at root level with mangled names.

Why It Happens

GitHub Wiki has no folder hierarchy. Every page renders at the wiki root. Folders in your source become part of the page name (with dashes).

wiki/getting-started/installation.md
  → renders at: /wiki/getting-started-installation

wiki/api/endpoints.md  
  → renders at: /wiki/api-endpoints

The Rules

1. All Pages Render at Root

Source: docs/guide/setup.md
URL:    github.com/user/repo/wiki/guide-setup

NOT:    github.com/user/repo/wiki/guide/setup  ❌

2. Links Must Use Flat Names

<!-- In wiki/getting-started/installation.md -->

<!-- ❌ WRONG — relative path -->
See [configuration](./configuration.md)

<!-- ✅ CORRECT — flat wiki name -->
See [configuration](getting-started-configuration)

<!-- ❌ WRONG — assumes hierarchy -->
See [endpoints](../api/endpoints.md)

<!-- ✅ CORRECT — flat wiki name -->
See [endpoints](api-endpoints)

3. _Sidebar.md Is Ground Truth

The sidebar defines your navigation. All links in _Sidebar.md must use flat names:

<!-- _Sidebar.md -->

**Getting Started**
- [Installation](getting-started-installation)
- [Configuration](getting-started-configuration)

**API Reference**  
- [Endpoints](api-endpoints)
- [Authentication](api-authentication)

Link Rewriting Automation

If you maintain wiki source in a folder structure, automate link rewriting on publish:

function rewriteWikiLinks(content, sourceDir) {
  // Convert relative paths to flat wiki names
  return content.replace(
    /\[([^\]]+)\]\(\.?\/?([^)]+)\.md\)/g,
    (match, text, path) => {
      // ./sibling.md → folder-sibling
      // ../other/page.md → other-page
      const flatName = path
        .replace(/^\.\.?\/?/, '')
        .replace(/\//g, '-');
      return `[${text}](${flatName})`;
    }
  );
}