Menu

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

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

DEV Community: github·linkbruno.com·about 1 hour ago
#nmgaKDJw
#devtogithub#technology#devto#dev#linux
Reading 0:00
15s threshold

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.…

Continue reading — create a free account

Join HashtagPLUS to read full articles, follow hashtags, vote, and join the conversation.