20241128 - Use Fumadocs for Documentation Site
Status
- Proposed
- Accepted
- Rejected
- Deprecated
- Superseded
Context
The Liam project required a documentation site framework that would provide a high-quality developer and user experience while being cost-effective and maintainable by the team. We needed a solution that would:
- Support static site generation for optimal performance
- Provide robust search capabilities
- Allow for customization and extension
- As a design-focused team, we wanted the ability to create impactful UI components for our documentation
- Offer a good developer experience for both code contributors and documentation writers
We evaluated several popular documentation frameworks to determine the best fit for our needs, focusing on Fumadocs, Nextra, and Mintlify.
Decision
We have decided to adopt Fumadocs as our documentation site framework.
The decision was based on a comprehensive evaluation of multiple factors:
Feature Comparison
| Feature | Fumadocs | Nextra | Mintlify |
|---|---|---|---|
| Static Generation | ✅ | ✅ | ✅ |
| Caching | ✅ | ✅ | ✅ |
| Light/Dark Mode | ✅ | ✅ | ✅ |
| Syntax Highlighting | ✅ | ✅ | ✅ |
| Table of Contents | ✅ | ✅ | ✅ |
| Full-Text Search | ✅ Free, with Algolia migration option | ✅ FlexSearch only | ✅ |
| Internationalization | ✅ | ✅ | ✅ |
| Last Edit Date | ✅ | ✅ | ✅ |
| Page Icons | ✅ | ✅ | ✅ |
| React Server Components | ✅ App Router support | ❌ Pages Router only | - (Users manage MDX only) |
| Remote Sources | ✅ | ✅ | ✅ |
| SEO | ✅ | ✅ | ✅ |
| Built-in Components | ✅ Rich variety | ✅ | ❌ Limited |
| Custom Components | ✅ | ✅ | ❌ |
| OpenAPI Integration | ✅ | ❌ | ✅ |
| TypeScript Docs Generation | ✅ | ❌ | ❌ |
| TypeScript Twoslash | ✅ | ✅ | ❌ |
| Styling | ✅ Flexible | ✅ Flexible | ❌ Paid for custom CSS/JS |
| Web Editor | ❌ | ❌ | ✅ In development |
| Thumbs up feedback | ❌ | ❌ | ✅ |
| Pricing | ✅ Free | ✅ Free | ❌ $150/month + $100/month for preview |
Key Adoption Factors
- Cost Efficiency: Fumadocs is open-source and free to use, aligning with our resource constraints
- Design Quality: Provides high-quality UI components with minimal code requirements
- Functionality: Offers comprehensive features needed for Liam documentation (full-text search, built-in components, theme switching)
- Extensibility: Being Next.js-based allows for extension with custom React components
- Hosting and Operations: Leverages our team's existing Next.js expertise for hosting and maintenance
- Marketing Opportunity: Potential visibility through listing on the Fumadocs showcase
Why Other Options Were Not Selected
-
Mintlify:
- Prohibitively expensive pricing model
- Usage-based billing for AI chat features beyond 250 queries with no apparent way to disable
- Slower deployment process
-
Nextra:
- Lacks App Router and React Server Components support
- Limited search capabilities (FlexSearch only)
- Fumadocs addresses these limitations while maintaining Nextra's positive attributes
Consequences
Positive
- No licensing fees, reducing project costs
- Modern documentation site with excellent UX for our users
- Integration with our existing Next.js knowledge and tooling
- Flexibility to customize and extend as our documentation needs evolve
- App Router and RSC support enables better performance and development experience
- Rich built-in components accelerate documentation creation
Negative
- Tailwind-based styling differs from Liam's CSS Modules approach, creating some inconsistency
- Requires self-hosting and domain management (though this is also an advantage for control)
- As a newer framework, the community and ecosystem are smaller than more established alternatives
Neutral
- Regular maintenance will be required to keep the documentation site updated
- The team will need to develop expertise in Fumadocs-specific features and configurations