A GitHub Wiki is a documentation space attached to a repository, editable in the browser, written in Markdown.
The detail that determines everything else about it: a Wiki is its own Git repository, separate from the one holding your code. It has its own history, its own clone URL, and — crucially — its own commits, which means a change to your code and a change to its documentation can never be the same commit.
That single architectural fact is the source of both the Wiki’s convenience and its central problem.
The separate repository
Section titled “The separate repository”Every Wiki has a clone URL formed by appending .wiki.git to the repository’s:
git clone https://github.com/OWNER/REPO.wiki.gitWhat it doesClones the Wiki of a repository as an ordinary Git repository.
Why we run itEditing several pages, doing a bulk find-and-replace, or reviewing the Wiki's history is far easier locally than through the browser editor.
Expected resultA normal clone, containing one Markdown file per Wiki page.
Inside, the structure is flat: one Markdown file per page, named after the page title, plus an
optional _Sidebar.md and _Footer.md rendered on every page.
Home.mdInstallation.mdConfiguration.md_Sidebar.mdYou can edit, commit and push these like any repository. That is genuinely useful — bulk edits, scripted updates and reviewing history all work — and it is also the clearest demonstration of why the Wiki drifts: nothing about pushing to your code repository touches this one.
Enabling and permissions
Section titled “Enabling and permissions”Wikis are enabled per repository and can be turned off:
gh repo edit OWNER/REPO --enable-wiki=falseTwo settings matter. Whether the Wiki is enabled at all, and — for public repositories — whether editing is restricted to collaborators or open to any GitHub user. The permissive setting made more sense in an earlier era of the web; today it is a spam vector, and restricting edits to collaborators is the sensible default.
The drift problem
Section titled “The drift problem”Here is the failure mode, and it is close to universal.
A team writes good Wiki documentation. Six months later the code has changed forty times and the Wiki has changed twice. The documentation is now confidently wrong — which is worse than absent, because a reader has no way to tell which parts are current.
The mechanism is structural rather than a discipline failure:
- The change and its documentation cannot be one commit. They are different repositories.
- Review never sees it. A pull request diff shows code; nothing prompts a reviewer to ask whether the Wiki still holds.
- CI cannot check it. Your tests do not fail because a Wiki page describes a removed flag.
- Nothing links them. Nobody notices the Wiki is stale until a user reports it.
Compare with documentation in a /docs directory of the same repository: the change and its
documentation land in one commit, appear in one diff, are approved by one reviewer, and
can be checked by CI — a link checker or a test that runs the documented commands.
Documentation that must match the code should live where the code lives, and change in the same commit.
That is the rule. Everything below is about the cases where it does not apply.
Where each documentation surface belongs
Section titled “Where each documentation surface belongs”| Surface | Versioned with code | Reviewed | Best for |
|---|---|---|---|
| README | Yes | Yes | What this is, install, quick start |
/docs directory | Yes | Yes | Reference and guides that must match the code |
| Wiki | No | No | Community notes, FAQs, meeting notes, scratch |
| GitHub Pages | Built from the repo | Yes | Published documentation sites with navigation and search |
README
Section titled “README”The front door. Should answer, in the first screen: what is this, who is it for, how do I install it, and what does the simplest possible use look like. Everything else can be a link.
/docs in the repository
Section titled “/docs in the repository”The default for technical documentation of any depth. Same repository, same pull request, same review, same CI. If the documentation describes behaviour, this is where it should be.
The cost is that it is read as Markdown files on GitHub rather than as a documentation site — which is what Pages solves.
Best for content that is genuinely not tied to a code version:
- Community-contributed guides and troubleshooting notes
- Meeting notes and decision records
- Long-lived FAQs
- Working notes that would clutter the repository
The common thread is content with no correct version. A troubleshooting note does not become wrong when you release v3.
When you want a real documentation site — navigation, search, versioning, styling — built from the
repository and deployed automatically. Content stays in /docs and is versioned with the code; Pages
is the publishing step. Covered in GitHub Pages.
A decision procedure
Section titled “A decision procedure”Three questions, in order:
- Does this become wrong when the code changes? Yes →
/docs, in the repository. This settles most cases. - Do people outside the team need to read it comfortably? Yes → publish
/docswith Pages. - Is it neither of those — community notes, FAQs, meeting records? → Wiki is reasonable.
If you cannot answer question 1 with confidence, the answer is /docs. The cost of versioned
documentation is a small amount of friction. The cost of unversioned documentation is silent wrongness.
Making a Wiki survivable
Section titled “Making a Wiki survivable”If you have one, or inherit one, a few things reduce the harm:
Date the pages. A visible “last reviewed” line lets a reader judge staleness themselves. It is crude and it works.
Maintain _Sidebar.md. Wikis have no automatic navigation beyond a page list. Without a sidebar,
a Wiki over about ten pages becomes unnavigable.
Audit it on a schedule. Because nothing else will. Clone it and look at the log:
git clone https://github.com/OWNER/REPO.wiki.gitcd REPO.wikigit log --format='%ad %s' --date=short -- . | head -20Migrate anything version-specific into /docs. Since the Wiki is a Git repository, this is an
ordinary file move plus a commit — not a rewrite.
Consider turning it off. An empty, disabled Wiki is better than a stale, enabled one. Disabling does not destroy the content: the Wiki repository remains and can be cloned.
Auditing a Wiki you inherited
Section titled “Auditing a Wiki you inherited”Inheriting a repository with a Wiki is common, and the first question is whether it is an asset or a liability. Because the Wiki is a Git repository, you can answer that with ordinary Git commands.
git clone https://github.com/OWNER/REPO.wiki.gitcd REPO.wiki
# When was anything last touched?git log -1 --format='%ad' --date=short
# Which pages are oldest?for f in *.md; do printf '%s\t%s\n' "$(git log -1 --format=%ad --date=short -- "$f")" "$f"done | sort
# How much is there?wc -w *.md | sort -n | tail -20A Wiki whose newest page is three years old, sitting on a codebase that changed last week, is documentation that will mislead someone. The choices are to migrate what is still true, or to disable it — and disabling does not destroy the content, since the repository remains clonable.
Migrating into /docs is a file move plus a commit, because both sides are Git:
cp REPO.wiki/Configuration.md ../repo/docs/configuration.mdcd ../repogit add docs/configuration.mdgit commit -m "Move configuration docs from the wiki into /docs
The wiki is a separate repository, so these could never change in thesame commit as the code they describe. They had drifted."Recording why in the commit message matters here. The next person to find an empty Wiki should not have to guess whether the content was lost or moved deliberately.
The Wiki’s own history
Section titled “The Wiki’s own history”Because it is a Git repository, everything Git offers applies:
git log --oneline -- Installation.mdgit diff HEAD~5 -- Installation.mdgit log -p --follow -- Configuration.mdThat is genuinely more capable than the browser interface for anything historical — and it is also the clearest demonstration of the separation, since none of it appears anywhere in your code repository’s history.
One consequence worth knowing: the Wiki has no branches in any useful sense. There is no review, no proposed change, no way to draft an update and have someone approve it. Every edit is a direct push to the only branch. For documentation that must be correct, the absence of review is a stronger argument against the Wiki than the drift.
When a Wiki genuinely earns its place
Section titled “When a Wiki genuinely earns its place”The lesson so far has been mostly cautionary, so it is worth being clear about where a Wiki is the right answer.
Community knowledge on a popular project. Troubleshooting notes, platform-specific workarounds, integration guides written by users. This content has no correct version, benefits from low-friction editing, and would be a burden if every contribution needed a pull request.
Meeting notes and decision records that are not versioned artefacts of the code.
Content that changes independently of the code. A roadmap, a list of related projects, a glossary.
A staging area. Working notes that would clutter the repository, later promoted to /docs once
they settle.
The common thread is that low editing friction is worth more than review, and no version of the
content is more correct than another. Whenever those two conditions do not hold, /docs is better.
Common mistakes
Section titled “Common mistakes”Treating the Wiki as documentation of record. It drifts, structurally, regardless of intent.
Leaving public Wiki editing open to everyone. Spam.
Assuming branch protection covers it. It does not; the Wiki is a different repository.
Documenting API behaviour or configuration flags there. Both change with the code.
No sidebar. Navigation collapses past a handful of pages.
Forgetting it exists. The most common outcome, and the reason so many projects have a Wiki whose last edit is four years old.
Exercise
Section titled “Exercise”- Enable the Wiki on your practice repository and create a page in the browser.
- Clone the Wiki with the
.wiki.gitURL and confirm the page is a Markdown file. - Add a second page locally, plus a
_Sidebar.mdlinking both, and push. - Confirm the sidebar renders on both pages.
- Now check
git login your code repository and observe that none of this appears there. - Move one page into
/docsin the code repository and note the difference: it now travels with the code, appears in diffs, and can be reviewed.
Step 5 is the point of the exercise. Seeing two entirely separate histories makes the drift problem concrete.
What you learned
Section titled “What you learned”- A Wiki is a separate Git repository, clonable at
REPO.wiki.git. - Because it is separate, code and documentation can never change in one commit — which is the structural cause of drift.
- Wiki edits bypass pull requests, review, branch protection and CI.
- Documentation that must match the code belongs in
/docs; Wikis suit content with no correct version. - Pages publishes versioned
/docscontent as a real site, keeping review and losing nothing. - A disabled Wiki is better than a stale one, and disabling does not delete the content.
The short version
Section titled “The short version”If you remember one thing: documentation that must match the code belongs in the same repository as the code, so the two change in the same commit and are reviewed together.
A Wiki cannot do that, structurally, because it is a different Git repository. That makes it right for content with no correct version — community notes, meeting records, long-lived FAQs — and wrong for anything describing how the software currently behaves.
If you inherit one, clone it, read its log, migrate what is still true into /docs, and disable it.
Disabling does not destroy anything; the Wiki repository remains and can be cloned at any time.
Before you enable one
Section titled “Before you enable one”Three questions, and if any answer is no, /docs is the better choice.
Will this content become wrong when the code changes? If yes, it must live where the code lives so the two change together.
Is low editing friction worth more than review? A Wiki has no pull requests, no approval and no CI. That suits community notes and suits documentation of record badly.
Will anyone maintain it? A Wiki whose newest page is three years old, attached to a codebase that changed last week, actively misleads people.
A Wiki that passes all three — community troubleshooting notes, meeting records, a long-lived FAQ — is genuinely useful. Most Wikis do not, which is why so many sit abandoned behind a tab nobody clicks.