MkDocs
Build a Manual with MkDocs #6: Maintenance — Search, Accessibility, and Documentation Culture
The final post in the series. We'll close it out from the operations perspective: refining Material's built-in search, accessibility that lets everyone read, and the Docs as Code culture that keeps docs alive for a long time.
Comparing Documentation Site Generators — Hugo, MkDocs, Docusaurus, Starlight: Which One to Pick
Once you've decided to build your team docs as a static site, the next question is which tool to build it with. We compare Hugo, MkDocs, Docusaurus, and Starlight across runtime, search, versioning, and ceiling, and lay out which to choose for which situation.
Build a Manual with MkDocs #5: Multilingual Docs and Versioning
We cover serving one set of docs in multiple languages and keeping older docs around as product versions move up. We'll add multilingual support with the mkdocs-static-i18n plugin, and attach version snapshots and a version selector with mike.
Build a Manual with MkDocs #4: Deploy on Cloudflare Pages and Connect a Domain
We send the docs we built locally out into the world. We'll pin dependencies with requirements.txt, push to GitHub and connect it to Cloudflare Pages, and attach a custom domain. We'll also touch on gh-deploy, MkDocs' built-in deployment.
Build a Manual with MkDocs #3: Writing Content — Code Blocks, Mermaid, and Admonitions
We cover three elements that make docs pleasant to read: code blocks with titles and line highlighting, Mermaid diagrams drawn as code, and admonitions that make cautions and warnings stand out. Here's how to use them in MkDocs Material.
Build a Manual with MkDocs #2: nav and Search — Shaping the Information Structure of Your Docs
Even as your docs grow to dozens of pages, a sidebar and search are what keep readers from getting lost. We'll design the nav directly in mkdocs.yml, turn on Material's navigation features, and enable the built-in search.
Build a Manual with MkDocs #1: From Install to Your First Doc
Set up the skeleton of a team documentation or product manual site with MkDocs and the Material theme. We'll go all the way from installing into a Python virtual environment, to creating a new site, applying the theme, and serving your first doc on a local server.