GitHub Wiki Is an Anti-Pattern: Why You Should Use /docs Instead

⏱️ Lectura: 9 min

Michael Heap found only one real reason to use the GitHub wiki instead of a /docs folder inside the repository itself: it’s always a click away. Everything else works against it, according to what he details in his article published on michaelheap.com.

📑 En este artículo

1. TL;DR
2. What happened
3. Background and history of the GitHub wiki
4. GitHub wiki vs. /docs folder: the technical comparison
5. How to get started
   1. Step 1: create the folder and the first document
   2. Step 2: install the GitHub CLI to migrate existing content
   3. Step 3: publish with GitHub Pages
6. Impact and analysis
7. What’s next
8. Frequently Asked Questions
   1. Does the GitHub wiki still serve a purpose?
   2. What happens if my /docs documentation grows too large?
   3. Do I need Jekyll to publish the /docs folder?
   4. Does the wiki support uploading your own images?
   5. How do I migrate the content I already have in the wiki?
   6. Does this approach work for a company’s private documentation?
9. References

The debate over where to store a project’s documentation on GitHub resurfaces every six months in developer forums and social networks, and Heap decided to settle it in writing after seeing it repeat that many times. His conclusion: the GitHub wiki is an anti-pattern for any team that already uses pull requests to review code.

TL;DR

• The GitHub wiki has just one real advantage: it’s a click away from anywhere in the repository.
• Storing docs in a /docs folder versions them alongside the code: each commit pins which documentation matches that version.
• Changes to /docs go through a pull request and peer review; the wiki gets edited without that control.
• GitHub Pages can publish the content of /docs automatically with an Actions workflow.
• Uploading images doesn’t work in the wiki: you have to host them on another service anyway.
• The just-the-docs theme lets you launch a documentation site with Jekyll without writing HTML from scratch.
• When /docs grows too large, migrating to its own repository is the natural next step.

What happened

Heap’s post starts from an uncomfortable premise for anyone defending the wiki: he initially planned to write something neutral, along the lines of “you can use the wiki or a docs folder, both are valid.” But when he listed the arguments for each option, he found only one point in the wiki’s column (that it’s always available with a click from the repository) against half a dozen in the /docs column.

That asymmetry is what led him to call using the wiki an anti-pattern: not because the feature is badly designed, but because there’s almost always a better alternative for the same job, with the same initial setup effort.

Background and history of the GitHub wiki

The GitHub wiki works, technically, as a separate Git repository running parallel to the project’s: every public repository (and several private ones) automatically gets a hidden one with the .wiki.git suffix. It’s edited from a simplified web interface, without going through a pull request, which made it attractive for years for quick notes, internal runbooks, or collaborative documentation that didn’t need formal review.

The alternative Heap proposes isn’t new: use a /docs (or /documentation) folder inside the code repository itself, and publish it as a static site with GitHub Pages. This practice became popular alongside site generators like Jekyll, and today dozens of ready-to-use themes coexist, including just-the-docs, built specifically for technical documentation.

GitHub wiki vs. /docs folder: the technical comparison

The core difference between the two options is version control. When documentation lives in /docs, each commit to the main repository pins which version of the documentation matches that version of the code: if someone needs to see how a feature was configured in an earlier version, checking out the corresponding tag is enough. The wiki, on the other hand, is a single history with no direct relationship to the project’s tags or releases.

Aspect	GitHub wiki	/docs folder
Versioned alongside code	No: separate, standalone history	Yes: each commit pins its version
Available when cloning the repo	Not by default (must be cloned separately)	Yes, always
Change review	Direct editing, no pull request	Pull request with peer review
Lint / CI over the content	Not applicable	Yes, for example with Vale in GitHub Actions
Support for hosting images	No: must be hosted on another service	Yes, alongside the repo’s files
Visual customization	Very limited, all pages look the same	Full, via a Jekyll/Hugo theme or custom CSS

The linting point deserves a concrete example: with documentation in /docs, a GitHub Actions workflow can run Vale on every pull request to catch style errors or banned terms, something impossible to automate over wiki content because it never passes through any CI pipeline.

How to get started

Migrating from the wiki to /docs doesn’t require new tools: Git is enough, and if you want to publish the result as a site, a GitHub account with Pages enabled.

Step 1: create the folder and the first document

mkdir docs
echo "# Project documentation" > docs/index.md
git add docs
git commit -m "docs: move documentation to docs folder"
git push origin main

This first commit already leaves the documentation versioned alongside the code: anyone who clones the repository has it available with no extra steps.

Step 2: install the GitHub CLI to migrate existing content

If you already had content in the wiki, you can clone it like any Git repository (it’s just another .git) and copy the Markdown files into /docs. To authenticate and automate the process, install gh, the official GitHub CLI:

# Windows (PowerShell, with winget)
winget install --id GitHub.cli

# macOS (with Homebrew)
brew install gh

# Linux (Debian/Ubuntu)
sudo apt install gh

gh auth login
git clone https://github.com/user/repository.wiki.git temp-wiki
cp temp-wiki/*.md docs/
rm -rf temp-wiki

Step 3: publish with GitHub Pages

From Settings → Pages in the repository, choose the main branch and the /docs folder as the source. GitHub builds the site with Jekyll automatically. If you prefer a different generator, an Actions workflow can build and publish the result:

name: Publish documentation
on:
  push:
    branches: [main]
    paths: ["docs/**"]
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v5
      - uses: actions/jekyll-build-pages@v1
        with:
          source: ./docs
      - uses: actions/deploy-pages@v4

With that workflow, every push touching files inside docs/ triggers an automatic build and publish. It’s the same pattern Heap describes to avoid relying on the gh-pages branch, which breaks versioning because it separates the published documentation from the code history.

Verify it’s live

To confirm Pages is serving the site, go to Settings → Pages: the top shows “Your site is live at” followed by the URL. You can also check it from the command line:

curl -I https://user.github.io/repository/

An HTTP/2 200 response confirms the site is published and accessible.

💡 Tip: leave a single page in the wiki (or disable it) that redirects to the site published at /docs, so anyone who lands there via the wiki’s shortcut finds the real content.

⚠️ Watch out: don’t use the gh-pages branch to publish: since it lives apart from the main history, it breaks the relationship between each version of the code and its corresponding documentation.

Impact and analysis

For teams and open source projects in Latin America, the argument carries extra weight: most Spanish-speaking maintainers already use pull requests as their single workflow, both for code and for translations. Folding documentation into that same workflow spares a new contributor from having to learn two different ways to propose changes: one for code, and another, without review, for the wiki.

There’s an honest exception Heap doesn’t ignore: on a very small team, without a formal review process, the wiki remains the lowest-friction option for quick internal notes that nobody needs to version. The cost of setting up /docs and Pages isn’t justified if the documentation is short-lived or only read by the team itself.

What’s next

Heap’s recommendation is clear while the project is young: use /docs because it has the best effort-to-benefit ratio to start with. The limit shows up when documentation grows so much that it needs its own build pipeline, its own review rules, or its own domain. At that point, migrating to a dedicated repository is a natural step, because contributors are already used to working with versioned documentation inside a repo.

flowchart TD
A["Documentation in /docs folder"] --> B{"Growing too large?"}
B -- "No" --> C["Stays in the same repo"]
B -- "Yes" --> D["Migrates to its own repository"]
D --> E["Independent build pipeline"]
D --> F["Own review rules"]

📖 Summary on Telegram: View summary

Try it yourself: create a docs folder in your repository today and enable GitHub Pages from Settings → Pages to see the published site in minutes.

Frequently Asked Questions

Does the GitHub wiki still serve a purpose?

Yes, for quick notes or internal documentation on a very small team that doesn’t need formal review or versioning alongside the code.

What happens if my /docs documentation grows too large?

It migrates to its own repository, with its own build pipeline and its own review rules, which Heap points to as the natural next step.

Do I need Jekyll to publish the /docs folder?

No, GitHub Pages uses Jekyll by default if you don’t configure anything else, but you can build with Hugo, MkDocs, or another generator and publish the result with the official Pages Action.

Does the wiki support uploading your own images?

Not directly: you have to host them on another service and link to them from the wiki page.

How do I migrate the content I already have in the wiki?

By cloning the hidden repository.wiki.git repository with Git and copying the Markdown files into the main repo’s /docs folder.

Does this approach work for a company’s private documentation?

Yes, it works the same way in private repositories, with the same access control the code repository already has.

References

• The GitHub wiki is an anti-pattern: Michael Heap’s original article laying out the central argument of this piece.
• GitHub Pages: official documentation for publishing static sites from a repository, including the /docs folder.
• just-the-docs: a Jekyll theme built specifically for technical documentation sites.
• Vale: a prose linter that can run in GitHub Actions over Markdown files.
• actions/deploy-pages: the official GitHub Action for publishing static content to Pages.

📱 Enjoy this content? Follow @programacion on Telegram for daily tech content in Spanish: quick summaries, fresh content every day. @programacion

Imagen destacada: Foto de Krishna Pandey en Unsplash