Building Web3 Developer Docs with Docusaurus

When I chose Docusaurus 3 for DPO2U's documentation site, the decision wasn't obvious. Here's why I picked it over Nextra, GitBook, and Mintlify — and the configuration decisions that shaped the final result.

Why Docusaurus

The Web3 documentation landscape has strong options. GitBook is popular for its simplicity. Mintlify is gaining traction with its clean design. Nextra offers tight Next.js integration. But for DPO2U, Docusaurus won on three criteria:

1. Full control over the output — no hosted platform lock-in, self-hosted via Docker
2. MDX support — React components inside documentation pages (critical for Tabs, interactive examples)
3. Mature plugin ecosystem — Mermaid, search, versioning all available as first-party or well-maintained plugins

Since DPO2U runs its own infrastructure on a VPS with Traefik, having a static site that builds to plain HTML and deploys via Docker Compose was the ideal fit.

Key configuration decisions

Mermaid for diagrams

Blockchain documentation without diagrams is incomplete. Every data flow, every contract interaction, every token movement is better understood visually.

Docusaurus supports Mermaid natively through @docusaurus/theme-mermaid:

// docusaurus.config.js
markdown: {
  mermaid: true,
},
themes: ['@docusaurus/theme-mermaid'],

With two lines of configuration, every Markdown code block tagged with mermaid renders as an interactive diagram — with automatic dark mode support.

Manual sidebar over auto-generated

Docusaurus offers auto-generated sidebars from the file system. It's convenient, but it's a trap for documentation that needs intentional information architecture.

I switched to a manual sidebar with five curated categories:

• Core Concepts — Introduction, Architecture, Tokenomics, Smart Contracts
• Agents & AI — Agent overview, The Brain, LEANN Framework
• Integration — Getting Started, MCP Server, Schemas
• About — DPO2U, One Person Unicorn, Frederico
• Contributing — Style Guide, Contributing, Changelog

This structure tells a story: understand the concepts, then the agents, then integrate, then learn about us, then contribute. An auto-generated sidebar would sort alphabetically and lose that narrative.

Prism language support

DPO2U's stack spans multiple languages. The default Prism configuration in Docusaurus covers JavaScript and TypeScript, but we needed more:

prism: {
  additionalLanguages: ['solidity', 'json', 'bash', 'rust', 'toml'],
}

Even though Compact isn't directly supported by Prism, using rust as the syntax highlighter provides reasonable results for Compact code blocks — the syntax overlap is close enough to be useful.

Blog as Dev Diaries

Docusaurus's blog plugin is underutilized by most documentation sites. For DPO2U, renaming it to "Dev Diaries" and using it as a build-in-public journal creates a secondary content channel:

blog: {
  blogTitle: 'Dev Diaries',
  blogSidebarTitle: 'Recent entries',
  blogSidebarCount: 'ALL',
}

The blog serves a dual purpose: it provides long-form writing samples for anyone evaluating the documentation quality, and it creates a timeline of technical decisions that adds context to the docs themselves.

Deployment

The site runs in a Docker container behind Traefik:

# docker-compose.yml (simplified)
services:
  docs:
    build: .
    labels:
      - "traefik.http.routers.docs.rule=Host(`docs.dpo2u.com`)"

Build times are under 30 seconds. The onBrokenLinks: 'throw' configuration catches dead links at build time, preventing broken references from reaching production.

What I'd do differently

If I were starting over:

• Set up the manual sidebar from day one — migrating from auto-generated to manual required touching every _category_.json file
• Establish the style guide before writing content — several pages needed terminology corrections after the fact
• Start with dark mode colors — I initially used the default green palette and had to refactor all custom CSS when switching to the indigo theme

Conclusion

Docusaurus is not the trendiest choice for Web3 docs, but it's the most controllable. For a project that values self-hosting, owns its infrastructure, and needs the flexibility of React components inside documentation — it's the right tool.

The source for this documentation site is available on GitHub.