Skip to main content
✓ Completed ⭐ Featured

WebDev Documentation Site

Technical documentation site with full-text search, MDX content, and dark mode. Built with Astro 5 and Pagefind for static search indexing.

View on GitHub Live Demo

Technology Stack:

Astro 5 TypeScript Tailwind CSS 3 MDX Pagefind Docker Nginx

Tags:

#Astro #TypeScript #Documentation #Search #MDX

Overview

Production-ready documentation site built with Astro 5 and static search capabilities. Features MDX content collections, Pagefind full-text search, responsive documentation layout, and dark mode support.

Key Features

Content & Search

  • MDX Content Collections: Type-safe documentation pages with frontmatter validation
  • Pagefind Integration: Static full-text search with 693+ words indexed
  • Search Keyboard Shortcut: Cmd/Ctrl + K for quick access
  • 4 Documentation Pages: Introduction, Installation, Quickstart guides

UI/UX

  • Responsive Documentation Layout: Optimized reading experience across devices
  • Dark Mode Toggle: Persistent theme switching with localStorage
  • Callout Components: Note, tip, warning, and danger admonitions
  • Shiki Syntax Highlighting: GitHub Dark theme for code blocks
  • Typography Plugin: Prose styling for readable documentation

Technical

  • TypeScript Strict Mode: Full type safety
  • ESLint + Prettier: Code quality and formatting
  • Conventional Commits: Commitlint for git message standards
  • Husky Git Hooks: Pre-commit linting and validation
  • Multi-stage Docker: Optimized production builds
  • SSL/TLS: Let’s Encrypt certificate with auto-renewal

Architecture

webdev-docs/
├── src/
│   ├── components/
│   │   ├── Callout.astro      # Admonition component
│   │   └── DocsHeader.astro   # Navigation header
│   ├── content/
│   │   └── docs/
│   │       └── getting-started/
│   │           ├── introduction.mdx
│   │           ├── installation.mdx
│   │           └── quickstart.mdx
│   ├── layouts/
│   │   └── DocsLayout.astro   # Documentation page layout
│   └── pages/
│       ├── index.astro         # Homepage
│       └── [...slug].astro     # Dynamic doc routes
├── Dockerfile                  # Multi-stage production build
└── docker-compose.yml          # Container orchestration

Performance

  • Build Time: ~1.7 seconds
  • Pages Generated: 4 static HTML pages
  • Search Index: 693 words across 4 pages
  • Docker Image: Nginx Alpine (minimal footprint)
  • HTTP/2: Enabled with TLS 1.3

Deployment

  • Host: Hetzner CX32 VPS (Ubuntu 24.04)
  • Container Port: 3002
  • Reverse Proxy: Nginx on host
  • DNS: docs.davidfdzmorilla.dev via Cloudflare
  • SSL: Let’s Encrypt with auto-renewal
  • Uptime: Production-ready with health checks

Quality Gates

All quality standards met:

  • ✅ TypeScript compilation: 0 errors
  • ✅ ESLint: 0 warnings
  • ✅ Prettier: Formatted
  • ✅ Build: Success
  • ✅ Docker: Multi-stage optimized
  • ✅ SSL: Valid certificate
  • ✅ Navigation: All links verified (v1.0.1 hotfix)

Releases

v1.0.1 (Hotfix)

  • Fixed navigation links (removed .mdx extension from URLs)
  • Added trailing slashes to all documentation links
  • Response time: 5 minutes from report to deployment

v1.0.0 (Initial Release)

  • Complete documentation site with search
  • MDX content collections
  • Responsive design with dark mode
  • Production deployment with SSL

Development Time

Total: 20 minutes (17:34 - 17:54 UTC)

  • Setup & configuration: 5 min
  • Content creation: 8 min
  • Deployment & verification: 7 min

Technologies

Built with modern web standards and tools:

  • Framework: Astro 5.17 (static site generation)
  • Language: TypeScript with strict mode
  • Styling: Tailwind CSS 3 + Typography plugin
  • Content: MDX with content collections
  • Search: Pagefind static indexing
  • Container: Docker with Nginx Alpine
  • CI/CD: Git hooks with Husky + lint-staged
Back to Projects