Every week, our team spent about 2 hours on docs infrastructure. Not writing docs — maintaining the system that serves them.
Rebuilding after a failed deploy. Fixing broken CI/CD pipelines. Updating dependencies in the docs framework. Debugging build errors that had nothing to do with the actual content.
We were using Docusaurus. It's a great tool, but it's a full app — with a build step, a deploy pipeline, and all the maintenance that comes with it.
One day I asked myself: why do we need a build step for markdown files?
The Hidden Cost of Docs Infrastructure
Here's what our docs workflow looked like:
- Write markdown in the repo
- Push to GitHub
- GitHub Actions triggers a build
- Docusaurus compiles the site
- Deploy to Vercel/Netlify
- Pray nothing breaks
When it worked, it was fine. But every few weeks something would break:
- Node version mismatch in CI
- A dependency update that broke the build
- CSS conflicts after a theme update
- Build timeouts on larger doc sets
Each incident cost 30-60 minutes of debugging. Multiply that across a year and you're looking at 100+ hours of engineering time spent on a system that serves static markdown.
What We Actually Needed
We took a step back and listed what we actually needed from docs:
- Markdown files in our GitHub repo (where we already write them)
- A clean, professional-looking site
- SEO so people can find our docs via Google
- Auto-sync when we push changes
- Zero maintenance
That's it. We didn't need a React app. We didn't need a plugin system. We didn't need to "own the build."
The Solution We Found
We switched to a hosted docs service that reads directly from GitHub. No build step, no CI/CD, no deploy config.
The workflow became:
- Write markdown in the repo
- Push to GitHub
- Done
The docs site updates in real-time. No pipeline, no build, no waiting.
We went with Docsbook — connected our repo and had a live docs site in about 30 seconds. The site is server-rendered (great for SEO), mobile-responsive, and supports AI-powered search.
The Before & After
| Before (Docusaurus) | After | |
|---|---|---|
| Time to update docs | Push → wait for build → verify | Push → done |
| Maintenance hours/week | ~2 hours | 0 |
| Build failures/month | 2-3 | 0 |
| CI/CD config files | 3 | 0 |
| Monthly cost | Free (but engineering time) | One-time $19 |
The real savings weren't the hosting cost. It was the engineering time we got back.
When This Approach Makes Sense
This isn't the right solution for everyone. If you need:
- Custom interactive components in your docs
- A fully custom design system
- Plugin architecture for extending functionality
Then a framework like Docusaurus or Nextra is the right call.
But if your docs are markdown files in a GitHub repo and you just want them to look professional and be findable on Google — you don't need a build pipeline for that.
Key Takeaway
The best docs infrastructure is the one you never think about.
We went from spending 2 hours/week fighting our docs system to spending zero. Our docs look better, they're indexed by Google, and we can focus on what actually matters — writing good documentation.
If you're maintaining CI/CD pipelines for markdown files, ask yourself: is this complexity necessary?
Have you dealt with docs infrastructure overhead? What's your current setup? I'd love to hear what's working (or not working) for your team in the comments.
Top comments (0)