Astro vs Docusaurus Documentation POC

A proof-of-concept comparing Astro and Docusaurus for building documentation sites, with a focus on component integration and framework flexibility.

🚀 Features

• Multi-framework support (Qwik, React)
• Server-side interactive components
• Documentation versioning
• Full-text search with Pagefind
• Dark/Light mode theming
• MDX support
• Syntax highlighting
• Table of contents navigation

🛠️ Tech Stack

• Astro v5.0.2
• Qwik v1.11.0
• React v18.3.1
• Tailwind CSS v3.4.15
• MDX v4.0.1
• Pagefind v1.2.0

🏃‍♂️ Getting Started

1. Clone the repository
2. Install dependencies:

pnpm install

3. Start the development server:

pnpm dev

4. Build for production:

pnpm build

📜 Available Scripts

pnpm dev         # Start development server
pnpm build       # Build for production (includes type checking)
pnpm preview     # Preview production build
pnpm docs:version # Create a new documentation version

📦 Project Structure

/
├── docs/                # Current documentation
├── docs-versions/       # Versioned documentation
├── src/
│   ├── components/     
│   │   ├── qwik/       # Qwik components
│   │   └── react/      # React components
│   ├── layouts/        # Astro layouts
│   └── pages/          # Routes
└── astro.config.mjs    # Astro configuration

🔍 Key Differences from Docusaurus

• Framework Flexibility: Mix Qwik and React components
• Performance: Zero JavaScript by default with selective hydration
• Server-First: Interactive components that work without client-side hydration
• Customization: Greater control over implementation details

🔧 Dependencies

Core

• astro - Core framework
• @astrojs/mdx - MDX support
• @astrojs/react - React integration
• @qwikdev/astro - Qwik integration

Styling

• @astrojs/tailwind - Tailwind CSS integration
• tailwindcss - Utility-first CSS
• @tailwindcss/typography - Typography plugin

Development

• typescript - Type checking
• @astrojs/check - Astro type checking
• tsx - TypeScript execution
• pagefind - Search functionality