Building Deployxa's Documentation
Good documentation is essential for a developer platform. If the docs are bad, developers will not use the platform, no matter how good the product is. Building good docs is a significant engineering challenge: the docs need to be fast (so developers can find what they need quickly), comprehensive (so developers can learn everything they need), searchable (so developers can find specific topics), and maintainable (so the docs stay up to date as the product evolves). Here is how we built Deployxa's documentation, the architecture we chose, and the lessons we learned.
The direct answer is that Deployxa's documentation is built with Astro (for the static site generation), MDX (for the content, which is Markdown with embedded React components), and Algolia (for the search). The docs are hosted on Deployxa's own infrastructure, which means they benefit from the same Traefik v3 routing, automatic SSL, and blue/green deployments as your apps. The docs are open source (hosted on GitHub), which means the community can contribute improvements and corrections. For more on Astro, see our article on deploying an Astro static site with API routes.
The Architecture
The documentation has four main components:
1. The frontend (Astro + MDX)
The frontend is an Astro app that renders the documentation pages. Astro is chosen for its performance (it produces static HTML with zero JavaScript by default, which means pages load instantly) and its MDX support (which lets us embed interactive React components in the docs). The frontend uses Tailwind CSS for styling and a custom design system for consistency.
2. The content (MDX files)
The content is written in MDX (Markdown with embedded React components), which means we can write prose in Markdown and embed interactive components (e.g., code editors, live demos, diagrams) where needed. The content is organized into sections (getting started, guides, API reference, etc.), with a sidebar for navigation.
3. The search (Algolia)
The search is powered by Algolia, which provides fast, typo-tolerant search across all documentation pages. The search index is built at build time (via Algolia's crawler) and updated whenever the docs are deployed.
4. The deployment (Deployxa)
The docs are hosted on Deployxa's own infrastructure, which means they benefit from the same Traefik v3 routing, automatic SSL, and blue/green deployments as your apps. The docs are deployed automatically when changes are merged to the main branch, via a GitHub Actions workflow.
Step-by-Step: How the Docs Are Built
Here is how the docs are built and deployed.
Step 1: Write the content
The content is written in MDX files, organized into sections. Each file has a frontmatter section (with title, description, and sidebar position) and a body section (with the prose and embedded components).
Step 2: Build the static site
When changes are merged to the main branch, a GitHub Actions workflow runs astro build, which produces a dist/ directory with static HTML, CSS, and JS files.
Step 3: Build the search index
The workflow runs Algolia's crawler, which indexes the static HTML and updates the Algolia search index.
Step 4: Deploy to Deployxa
The workflow deploys the dist/ directory to Deployxa, which serves it via a static file server behind Traefik v3. The deployment is atomic (blue/green), which means there is no downtime during updates.
Step 5: Verify
The workflow runs deployxa doctor to verify the deployment is healthy. If the health check fails, the workflow rolls back to the previous version.
Common Pitfalls and Troubleshooting
The first pitfall is outdated docs. Documentation that does not match the product is worse than no documentation, because it misleads developers. The fix is to update the docs whenever the product changes, and to have a review process that catches discrepancies. The second pitfall is poor search. If the search is slow or inaccurate, developers will not find what they need, which means they will get frustrated and leave. The fix is to use a dedicated search service (like Algolia) that provides fast, typo-tolerant search, and to monitor the search analytics to identify and fix common queries that return no results. The third pitfall is poor navigation. If the sidebar is confusing or incomplete, developers will not be able to find the pages they need. The fix is to organize the content into clear sections (getting started, guides, API reference) and to test the navigation with real users. The fourth pitfall is slow page load. If the docs are slow to load, developers will get frustrated and leave. The fix is to use a static site generator (like Astro) that produces fast static HTML, and to optimize images and other assets. The fifth pitfall is lack of examples. Documentation without examples is hard to understand, because developers learn best by seeing code. The fix is to include code examples for every concept, and to make the examples copy-pasteable.
How the Docs Integrate with the MCP Server
The docs and the MCP server work together to provide a great developer experience. The docs are the human interface (for reading and learning), and the MCP server is the AI interface (for deploying and managing). For example, a developer might read the docs to learn how to deploy a Next.js app, then use the MCP server (via Cursor or Claude Desktop) to actually deploy it. The docs include MCP server examples (e.g., "say 'deploy my app' in Cursor to trigger the deployment"), which bridges the gap between reading and doing. For more on the MCP server, see our article on giving Cursor cloud superpowers.
Lessons Learned
Building the docs taught us several lessons. First, docs are a product, not an afterthought. We invested significant engineering time in the docs architecture, the design, and the content, because good docs are essential for a developer platform. Second, examples are everything. Developers learn best by seeing code, so we include code examples for every concept, and we make the examples copy-pasteable. Third, search is critical. Developers use search to find what they need, so we invested in Algolia (which provides fast, typo-tolerant search) and we monitor the search analytics to identify and fix common queries. Fourth, the docs need to be maintained. As the product evolves, the docs need to evolve too, which means we have a process for updating the docs whenever the product changes. Fifth, the community can help. By making the docs open source, we let the community contribute improvements and corrections, which keeps the docs accurate and comprehensive. For more on documentation patterns, see our article on the heuristic advisor, which is about translating errors into plain English (a form of documentation).
Advanced Documentation Patterns
Beyond the basics, documentation benefits from several advanced patterns. The first is interactive examples. Instead of static code blocks, the docs can include interactive examples (e.g., a code editor that lets the user modify the code and see the result), which makes the docs more engaging. The second is versioned docs. For platforms that evolve quickly (like Deployxa), versioned docs let users access the docs for a specific version, which prevents confusion when the platform changes. The third is community contributions. By making the docs open source (on GitHub), the community can contribute improvements and corrections, which keeps the docs accurate and comprehensive. The fourth is analytics. By tracking which pages are viewed most and which searches return no results, you can identify gaps in the docs and prioritize improvements. The fifth is multilingual docs. For platforms with a global audience, multilingual docs make the platform accessible to non-English speakers. For more on documentation, see our articles on the heuristic advisor and the auto-detection engine.
When Custom Documentation Is Not Needed
Building custom documentation is not always needed. For small projects, the framework's default documentation (e.g., Next.js's docs, Express's docs) is sufficient. For internal tools, a simple README is enough. For open-source projects, GitHub's built-in wiki might be sufficient. The key is to match the documentation to the project's needs: for developer platforms (like Deployxa), comprehensive custom documentation is essential; for small projects, simpler documentation is fine. For more on documentation patterns, see our articles on how we built the dashboard and the cost optimization engine.
Conclusion: Docs Are a Product
Good documentation is essential for a developer platform, and building good docs is a significant engineering challenge. By choosing the right architecture (Astro + MDX + Algolia), organizing the content clearly, and maintaining the docs as the product evolves, we built documentation that helps developers succeed with Deployxa. For more on Deployxa's engineering, see our articles on the auto-detection engine and the cost optimization engine. Learn about how we handle SSL at scale and how we built the dashboard in our companion articles. Explore our free developer tools to speed up your workflow. Try Deployxa Drop for an instant live preview with zero signup.