linkbruno.com

Posted on Nov 15

Moving docs from a GitHub wiki to a docs site? An 11-point checklist so the links survive

#webdev #opensource #github #documentation

Scheduled broken-link and redirect checks that tell you the moment a link breaks — linkbruno.com

A GitHub wiki is a fine place to start a project's documentation. It's right there, anyone with access can edit it, and it needs no build step. Eventually most projects outgrow it: they want versioned docs, search, review on pull requests, a custom domain. So they move to MkDocs, Docusaurus, Starlight, Sphinx or similar.

The new docs site goes live, and the wiki becomes either a stale copy or a single page saying "We've moved". And the links people have been posting for years, in issues, in commit messages, in Stack Overflow answers, in blog posts and in tutorials, start leading nowhere useful.

GitHub wikis don't support server-side redirects, so this needs more planning than a normal site move. Here's the checklist.

Before the move

1. Inventory every wiki page and its URL

Clone the wiki. It's a separate Git repository:

git clone https://github.com/OWNER/REPO.wiki.git
ls REPO.wiki

Each file maps to a URL: Getting-Started.md becomes https://github.com/OWNER/REPO/wiki/Getting-Started. Make a spreadsheet or CSV of every page and its wiki URL. That list is the basis for everything that follows.

2. Find out which wiki pages people actually link to

You can't get full analytics for a wiki, but you can find the links that matter most:

Search your own issues, pull requests and discussions for /wiki/. GitHub's search does this across the repo.
Search the code: git grep -n "/wiki/" in the main repo, including READMEs, docs, error messages and CLI help text.
Search the web for your wiki URL in quotes, and look at the repo's traffic page (Insights, Traffic) for referring sites.

The pages that show up here are the ones that need a perfect landing spot on the new site.

3. Map every page to a new URL before you start writing

For each wiki page, decide the exact new URL. Keep the mapping one-to-one where you can. If several wiki pages merge into one new page, map each to the right section anchor (/install/#linux), not just to the page.

Write the mapping down as data, not prose:

wiki_page,new_url
Getting-Started,https://docs.example.org/start/
Installation-on-Linux,https://docs.example.org/install/#linux
FAQ,https://docs.example.org/faq/

You'll use it three times: to write the redirect pages, to update links in your repo, and to test.

4. Convert the wiki's link syntax

Wiki pages link to each other with [[Page Name]] or [[Text|Page-Name]], which no docs generator understands. Convert these to normal Markdown links pointing at the new paths during migration, and run a link check on the converted docs before anything goes live.

During the move

5. Replace each wiki page with a pointer, not a deletion

Since the wiki can't redirect, the next best thing is to keep every page and replace its content with a short note and a link to the exact new location:

This page has moved to **[Installation on Linux](https://docs.example.org/install/#linux)**.

Generate these from the mapping file with a short script, so every page gets one and none point at the docs homepage. A pointer to the right page is far more useful than a generic "the docs moved" note.

6. Decide whether to disable the wiki at all

Turning off the wiki in repo settings makes every wiki URL redirect back to the repo's main page. That's tidy, but it throws away the pointer pages from the previous step. For most projects, keeping the wiki enabled, with editing restricted to collaborators and every page replaced by a pointer, is the better trade-off.

7. Update every link you control

Use the mapping to rewrite links in the main repo: README, contributing guide, issue and PR templates, code comments, error messages, CLI --help output, package metadata (homepage and documentation fields), and the repo's website field. Error messages and CLI help are the easy ones to forget, and they ship in installed copies for years.

Wiki moves are where links quietly die. linkbruno.com checks the new docs site on a schedule and tells you the moment a migrated link breaks.

After the move

8. Check that every old URL leads to the right place

Run through the mapping and verify that each wiki URL loads, contains the new link, and that the new link resolves. A short script that fetches each pointer page, extracts the link and requests it will catch typos in the mapping.

9. Check the new site for broken links on every build

Docs generators can usually fail the build on broken internal links (MkDocs --strict, Docusaurus onBrokenLinks: 'throw'). Turn that on now, while the docs are fresh, rather than after the first pile of broken links appears.

10. Update the most important external links

You can't fix every blog post, but you can fix the ones you own and the most visible ones you don't: your project's listing in package registries, awesome-lists that link the wiki, and highly voted Stack Overflow answers (an edit suggestion to update a moved link is usually accepted).

11. Recheck in a month

Some links only surface over time, as people revisit old bookmarks. A month after the move, look at which wiki pages still get visits (if you can tell) and run a crawl of the new docs site plus the pointer pages. External checkers such as linkbruno.com can do the crawl side of this on a schedule.

The short version

Clone the wiki, map every page to an exact new URL, replace pages with precise pointers instead of deleting them, rewrite every link you control from the same mapping, and turn on broken-link checks in the new docs build from day one.

DEV Community