GitHub Wikis Don't Bother

🦦 So, What Even Is a Git Wiki?

Important

🦄 Be sure to read the home page first - it covers key context you’ll want to know.

Welcome to the behind-the-scenes of this project's documentation! If you’ve ever wondered, “What’s a git wiki? Isn’t that just like GitHub Pages or a docs site?” — you’re in the right spot.

ELI5: What’s a Git Wiki?

Imagine a git wiki as a collaborative notebook, but built directly into your repository. It’s a place for living documentation: you can jot down how-tos, tips, process guides, or literally anything you want your future self (or teammates) to find quickly — all using markdown files, tracked by git.

• Versioned like your code: Roll back changes, blame edits, even create branches for docs work!
• Editable via the web: Edit right from the repo’s “Wiki” tab (no local clone needed).
• Markdown-first: Write docs just like README.md, with all the .md flexibility.
• Separate repo (under the hood): Wikitized docs are technically in their own git repository attached to your main project.

How Is This Different From GitHub Pages?

GitHub Pages is for static sites. Think: you build a website (maybe with React, Docusaurus, or plain HTML) and GitHub Pages will host it for you. It’s perfect for full-blown docs sites, landing pages, or anything that needs custom themes and interactivity.

• GitHub Pages = Website: Supports static site generators, full customization, and works great for docs that need to look fancy or have search, navigation, etc.
• Git Wiki = Notebook: Fast, frictionless, no build step, and built right in for repo-level docs or team guides.

Why Not Just Use a Static React Site for Docs?

You totally could! (And I will probably add that at some point, too!) But for now, I chose the git wiki because:

• Curiosity Factor: I’ve never worked with one before and wanted to see how it ticks firsthand
• Zero setup: No build scripts, no web hosting, just markdown and git
• Quick edits: Update docs right alongside your repo updates with no fuss
• Collaboration: Makes it way easier for (future?) contributors to leave tips, FAQ, and design notes — especially if they don’t want to learn another static site generator

But What If I Don’t Want to Use a Wiki? 🤷‍♀️

Don’t want a wiki? No problem - here’s exactly how to swap it out or replace it with a docs folder instead.

Important

🦄 Honestly, had I know this thing was going to be this much of a pita I would have never bothered! It's not worth it. It's like GitHub started this way back 20 years ago and then gave up 🤷‍♀️ Seems like it hasn't been touched much since...

---

🚀 Swapping (or NUKING) the Wiki in Your Own Template

So you’ve started your project from this template — nice! But maybe you want your own fresh docs space, or you’d rather not have a wiki at all. Here’s exactly how to do either, no drama required.

🦄 Good call! I suppose it's nice if you want them versioned separately (for some reason that's beyond me) or if you need to collaborate? Again - why not just use regular docs? Save yourself the trouble!

Scenario 1: Make the Wiki Your Own (aka "The Clean Takeover")

1. Clone Your Repo & Enable the Wiki
   Head to your repo’s Settings → Wiki, and make sure it’s enabled.

2. Clear Out the Template Pages
   Go to the Wiki tab and manually delete or overwrite each page to start from scratch, or edit them to fit your style.

3. Update Links
   Search your repo for any links pointing to old wiki pages and swap them to your new pages.

Scenario 2: Replace the Wiki With a /docs Directory

If you’d rather have plain markdown docs tracked in your main repo (or you want to use a static site generator later), here’s the quick and dirty method:

1. Create `/docs` Directory

   • In your project root, add a folder named docs.
   • Move any markdown docs you want to keep into docs/.
   • Update links in your README or docs index page to reference the new location (/docs/your-file.md).

2. Delete the Wiki Submodule

   • Look for the .gitmodules file and delete it
   • Scan your .git/config file for a  [submodule "wiki"] section and delete it, too
   • Run:

     git rm --cached wiki
     rm -rf wiki

3. Search Remaining Wiki References

   • Run a quick "Find All" across your repo to catch any lingering /wiki references—swap each one to /docs so all your links stay fresh.

4. (Optional) Add Docs Index

   • Add a README.md file inside your docs/ folder—GitHub will automatically show this as the homepage whenever someone browses into /docs.

Scenario 3: Automatically Sync Your /docs Folder to the Wiki

Want the best of both worlds? Check out GitHub Wiki Action. It keeps your /docs folder and your repo wiki in sync—no submodules, no hassle, and updates every time you push. Super simple!

🦄 I haven’t personally tried this one yet, but it looks like a slick way to automate your docs. Worth a look if you want to keep using markdown but don’t want the submodule headaches.

⌫ Heads-Up: What Actually Gets Deleted?

• .gitmodules (if the wiki was a submodule)
• The wiki/ folder in your root directory
• Wiki links in other markdown files

After that, you’re totally free to set up Docusaurus, mkdocs, or keep it simple with markdown!