Building in Public | Choosing a Documentation Tool

TL;DR After comparing a handful of documentation tools, I found MkDocs with the Material theme was the best fit for my project.

As I continue building my knitting calculator iOS app in public, I’ve started thinking about internal documentation — not for end users, but for myself and any developers who might want to peek into or contribute to the codebase.

Photo by Alexander Grey on Unsplash

Documentation Tools

I am already familiar with GitHub Pages, having used it briefly in the past — not extensively, but enough to know it could be a straightforward way to host developer documentation. Still, I'm not familiar with the full range of tools out there, so my first step is to explore the landscape and see what options exist.

I asked ChatGPT for a list of common documentation tools. Here I talk through each one:

✅ GitHub Pages with Markdown

This is the obvious starting point. GitHub Pages is essentially a static site generator (SSG). All I’d need to do is write Markdown files, drop them in a /docs folder, and GitHub would render them nicely. And serve them at

https://<username>.github.io/<repository>/

No build step, no hosting concerns — it’s as easy as it gets. You even get syntax highlighting! But it’s also limited. There’s no built-in search, no sidebar navigation, and limited formatting (for example, no built-in admonitions— styled blocks for notes, tips, and warnings). Note: With the free tier of GitHub, GitHub Pages is only available in public repos. However, even without GitHub Pages, your docs will still be readable and nicely rendered on GitHub, just not hosted as a standalone website.

✅ MkDocs with the Material Theme

MkDocs is an SSG that converts Markdown files into a structured documentation site. The Material theme adds a clean UI, responsive layout, full-text search, and support for admonitions. It’s a small amount of setup, but it offers a much more polished experience.

MkDocs is an open-source project developed and maintained by the open-source community, primarily by contributors on GitHub. It was originally created by Tom Christie, who’s also known for creating Django REST Framework.

• GitHub repo: https://github.com/mkdocs/mkdocs

• Maintained by volunteers and contributors.

The "Material for MkDocs" theme is inspired by Google's Material Design, but it’s not created or maintained by Google. It’s developed and maintained by Martin Donath, an independent developer (i.e., it's a third-party theme). He’s built a polished and feature-rich theme that adheres to Material Design principles.

• GitHub repo: https://github.com/squidfunk/mkdocs-material

• Official site: https://squidfunk.github.io/mkdocs-material/

It includes tons of thoughtful features like:

• Full-text search

• Responsive layout

• Versioning support

• Keyboard navigation

• Admonitions, tabs, and diagrams

✅ Docusaurus

This one’s a heavier-weight option, built on React. It offers powerful features like versioning, custom components, and plugin support — perfect for large OSS projects or developer platforms. But for my needs, it feels like overkill. ✅ Docsify

Docsify skips the usual build step entirely — instead of generating static HTML, it loads and renders your Markdown files directly in the browser with JavaScript. The upside is a super simple setup: drop in an index.html, add your .md files, and you’ve got a live documentation site with instant updates. This makes it great for lightweight projects or quick internal docs. The tradeoff is that features like search and theming often require plugins, it’s not as SEO-friendly as pre-built sites, and performance can lag if the docs get large. For a project I want to keep maintainable and contributor-friendly, these tradeoffs sound limiting compared to MkDocs. Docsify sounds like it's intended as a lighter-weight option than what I'm going for. ✅ GitBook

GitBook is a hosted documentation platform that lets you write in Markdown (or use its web editor) and publish your docs with built-in search, navigation, and a clean, modern UI. It’s polished and easy to use, with collaboration features like comments and integrations for larger teams. Because it’s a managed service, you don’t need to think about hosting or CI/CD — you just push content and GitBook handles the rest.

I'm leaning away from GitBook because it introduces vendor lock-in. While it does offer a free plan, many advanced features are gated behind paid tiers. I think GitBook would probably be overkill for my needs. Also, unlike MkDocs, it's not open-source, and I'm leaning towards open-source tools for this project.

✅ Sphinx

Sphinx is a documentation generator originally created for Python projects, and it remains the standard in that ecosystem. It’s extremely powerful: it supports reStructuredText and Markdown, offers robust cross-referencing, theming, and an extensive plugin system. Many large open-source projects (like Python itself) use Sphinx because it scales well and produces highly structured, professional-grade docs.

I probably won't use Sphinx since it has a steep learning curve, a heavier setup, and feels like overkill for a small iOS app. Its reliance on reStructuredText for many features also adds friction compared to a Markdown-first tool like MkDocs. For my use case, Sphinx feels more heavyweight than necessary.

My Requirements

Now that I understand some of the common features offered by these documentation tools, I am better able to evaluate which features I actually need — and which I don’t.

Some things are non-negotiable:

• I want the docs to live in the same GitHub repo as the code, fully under version control. For me, it's absolutely paramount that the documentation live in the source code repository. This way, documentation changes that accompany code changes are part of the same pull request and included in code review (as they should be).

• I want the docs to be publicly viewable, since this is an open-source project.

Some features an’t strictly necessary, but feel really nice to have:

• Search: Not essential, but highly likely to come in handy, especially for external developers trying to navigate unfamiliar content.

• Navigation: A clear sidebar or page structure would make the docs feel much easier to explore.

• Admonitions: I love this feature in MkDocs — it lets you highlight important tips, gotchas, or notes in a visually distinct way.

And some things I don’t need at all:

• Site-level versioning: Since this is just a standalone iOS app (not an API or library), I don’t need to maintain multiple live versions of the docs.

• I don’t need to host the docs on a custom domain — GitHub Pages is perfectly fine.

My Final Decision

While I was initially leaning toward GitHub Pages for its simplicity — no build step, no external tools, just Markdown in a folder — it became clear that I’d miss out on key features like search, navigation, and admonitions.

So I’ve decided to go with MkDocs using the Material theme, hosted on GitHub Pages.

It offers just the right balance of structure and simplicity. I still get to write my docs in Markdown, everything stays in version control, and I get a much more polished, contributor-friendly experience.

As a quick proof of concept, I set up a public repo on GitHub, added a docs/ directory, an mkdocs.yaml config file and a GitHub Action to serve it. You can have a look at the repository here and the documentation it produces here.

---

What do you use for internal documentation on your personal projects? Have you tried MkDocs, Docusaurus, or something else entirely? Let me know in the comments — I’d love to hear what works for you!