The GitHub wiki is an anti-pattern

Using the GitHub wiki is labeled an anti-pattern because its single real advantage - easy one-click access from the repo - is vastly outweighed by practical shortcomings. Wikis aren’t versioned alongside code, aren’t included when someone clones the repository (cloning the wiki is a hidden, separate step), and edits bypass the pull-request review workflow. They also block common CI and editor tooling: you can’t lint docs with GitHub Actions (e.g., Vale) or rely on local editor spellcheck workflows as easily, wikis offer limited branding customization, and they don’t support image uploads natively. Those specifics make collaboration, review, maintenance, and reproducible documentation workflows harder compared with keeping docs in the same repository as code.

The recommended approach is to place documentation in a /docs folder inside the repo so docs are versioned with the code, and publish them via GitHub Pages rather than using a gh-pages branch (which severs versioning parity). For quick starts, use the just-the-docs theme and GitHub’s build; for advanced setups, build with Hugo or similar and publish with a GitHub Action. Keep a single wiki page that simply points users to the hosted docs. When documentation outgrows a folder, migrate to a dedicated docs repository with its own build and PR processes - contributors will already be accustomed to repo-centric documentation workflows.