When my project Cascade started growing, I did what every developer does — I kept stuffing everything into the README.
The README Problem
A README is just one file. One very long, very scrollable, very hard to navigate file.
At some point I had:
- A project overview
- Local setup instructions for the backend
- Local setup instructions for the frontend
- Environment variable explanations
- API endpoint documentation
- An architecture diagram
- A roadmap
All in one file. It was a mess. Nobody was going to read that.
What are my actual options here?
Option 1: Just Keep the README
Simple. But past a certain size, a README stops being documentation and starts being a wall of text. No navigation. No search. No structure. Just Ctrl+F and hope.
Option 2: Build My Own Documentation Site
This felt like the right call at first. Full control, custom design, exactly what I want.
Then I started thinking about what “building my own doc site” actually means:
- Routing between pages
- A sidebar that stays in sync with my content
- Full text search
- Dark mode and light mode
- Mobile responsiveness
- Deployment and hosting
- Maintaining it forever alongside my actual project
That last point killed it for me. I would now be maintaining two projects — Cascade and a documentation app for Cascade. Every hour spent on the doc site is an hour not spent on the actual product.
Option 3: Docusaurus
Docusaurus is a static site generator built specifically for documentation. It is made by the Meta open source team and is what powers the docs for React, Supabase, TipTap, and dozens of other major projects.
The pitch is simple:
You own the content. Docusaurus owns everything else.
You write Markdown files. Docusaurus turns them into a complete, production-ready documentation website.
What Does “Everything Else” Actually Mean?
This is the part that surprised me. Out of the box, with zero configuration, you get:
Sidebar navigation — automatically generated from your folder structure. Create a file, it appears in the sidebar. No manual configuration.
Full text search — Docusaurus integrates with Algolia DocSearch for free for open source projects. Users can search across your entire documentation instantly.
Dark mode and light mode — built in, works on day one. You don’t write a single line of CSS for it.
Mobile responsive layout — the sidebar collapses into a hamburger menu on mobile automatically.
Versioning — if your API changes, you can maintain v1 and v2 docs simultaneously. Users pick which version they want to read.
A blog — comes included if you want to write release notes or engineering posts alongside your docs.
The File Structure Is Familiar
If you have used SvelteKit or Next.js, this will feel immediately familiar. Docusaurus uses the same file-based routing concept — your folder structure becomes your URL structure.
docs/
├── intro.md → /docs/intro
├── getting-started.md → /docs/getting-started
└── api/
├── auth.md → /docs/api/auth
└── documents.md → /docs/api/documents
Create a folder, create a Markdown file, done. The sidebar updates automatically.
But Wait — What About Deployment?
This was the part I was most worried about. Surely maintaining a deployed documentation site adds overhead?
Not really. You deploy Docusaurus to GitHub Pages in one command:
npm run deploy
After that, you set up a GitHub Action that automatically rebuilds and redeploys every time you push a new Markdown file. The entire pipeline looks like this:
You write a new .md file
↓
git push
↓
GitHub Action builds the site
↓
GitHub Pages serves the updated docs
↓
You never think about deployment again
Zero maintenance. Zero cost. The Docusaurus team maintains the framework. You just write content.
MDX — Markdown That Can Do More
Standard Markdown gets you far, but Docusaurus supports MDX — Markdown that can contain React components.
This means your documentation can be interactive:
## Try it live
<ApiPlayground endpoint="/auth/callback" />
## Response shape
<CodeBlock language="json">
{
"status": "success",
"email": "[email protected]"
}
</CodeBlock>
Live API explorers, tabbed code examples, interactive diagrams — all inside your Markdown files. You are not limited to static text.
The Honest Tradeoff
Docusaurus is not perfect for every situation. It is a framework — which means you are working within its structure, not defining your own. If you want a radically custom documentation experience, you will fight it.
But for 95% of projects, the built-in structure is exactly what you need. And the time you save not building routing, search, and dark mode from scratch is time you spend writing actual documentation that actually helps people.
The One Line Summary
Docusaurus is to documentation what SvelteKit is to web apps.
It handles all the boring infrastructure so you can focus on the one thing that actually matters — the content.
If your README is getting long and you are thinking about building a doc site from scratch, don’t. Spend an afternoon setting up Docusaurus and spend the rest of your time writing docs that people will actually read.
Built the docs for Cascade — a rich text editor with AI and cross-platform publishing workflows — using Docusaurus.
Connect with me : Linkedin
The Headache Of Maintaining Documentations In Production was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
