Docusaurus/MkDocs 的 24 小時工作流程：從 repo README 建立專業文件網站
From repo README to professional docs site in 24 hours — the exact Docusaurus/MkDocs workflow
這套 Docusaurus/MkDocs 工作流程可在 24 小時內把程式碼庫 README 等原始內容整理成上線的專業文件網站。流程包括規劃資訊架構、重組內容、根據 OpenAPI 規格生成 API 參考，並透過 GitHub Actions 在每次合併後建置，再部署至 GitHub Pages、Netlify 或 Vercel。同一團隊建置第二個網站時，若已有部署流程，需時半天。
Your product ships Friday. Your documentation is a 3-year-old Confluence page and a README nobody has touched since launch. That mismatch quietly costs you users, support tickets and contributor goodwill.
Here is the exact workflow I use to go from raw repo content to a live, professional documentation site in 24 hours.
1. Pick the framework in 10 minutes
- Docusaurus (React): best when you need API reference pages, MDX components, heavy versioning, or a React-based landing page around the docs.
- MkDocs + Material (Python): best when you want the fastest setup, a beautiful theme out of the box, and a simpler mental model for non-developer contributors.
Decision rule: if your content is maintained by developers in a repo, either works — pick the one matching your stack's language.
2. Bootstrap with intent (not the default demo)
scaffold -> theme config -> nav structure. The information architecture matters more than the theme: versioned docs, guides separated from reference, a search that actually works. Do this before writing a single page.
3. Restructure the content
- Convert buried Markdown into the new sidebar structure (fix every relative link — this is where migrations die)
- Split wall-of-text pages into scannable sections
- Move setup/quickstart to the front page — users decide in 30 seconds
4. Generate the API reference from OpenAPI
If the product ships an API, never hand-write the reference. Generate it from the OpenAPI spec (Redoc, Stoplight, or the Docusaurus OpenAPI docs plugin) so it regenerates on every spec change.
5. CI/CD so docs can never go stale
GitHub Actions on every merge -> build -> deploy to GitHub Pages/Netlify/Vercel. Docs PRs go through review like code PRs. A docs site without CI is a wiki — it rots.
6. The finishing checklist I run on every deliverable
- All internal links resolve (link checker in CI)
- Mobile nav usable, dark mode correct
- Full-text search returns relevant results
-
sitemap.xmlclean, and anllms.txtso AI assistants index the docs properly - Deployment proof: the site rebuilds from a clean clone
That's the whole system. The "24 hours" is real when the pipeline exists — the second site for the same team takes half a day.
I run this as a service for software teams (24h turnaround, Docusaurus and MkDocs). If you have questions about your own docs setup, ask in the comments — happy to help.
來源：DEV Community · dev.to