Description

Implement the main documentation browser UI for CrystalDocs.org, allowing users to browse and read auto-generated Crystal shard documentation.

Requirements

Homepage/Browse Page

• List of all shards with documentation
• Search functionality to find shards
• Filter by shard category/tags
• Display doc build status per shard

Documentation Viewer

• Render documentation HTML from MinIO
• Proper styling for Crystal docs (classes, methods, modules)
• Syntax highlighting for code examples
• Left sidebar: navigation tree (modules, classes, methods)
• Right content area: selected documentation page

Version Switcher

• Dropdown to switch between shard versions
• Show available versions for current shard
• Persist selection when navigating docs
• Default to latest stable version

Navigation

• Breadcrumbs showing current location
• Search within documentation
• Links to source code on GitHub
• Link back to CrystalShards.org package page

Technical Details

• Use Lucky framework's HTML rendering via BrowserAction
• Fetch docs from MinIO storage service
• Create actions under `apps/crystaldocs/src/actions/`
• Create pages under `apps/crystaldocs/src/pages/`
• Wire up to existing ShardVersion model (shared database)
• Responsive design with modern CSS
• Implement routing for versioned docs

URL Structure

```
/ # Homepage with shard list
/shards/:shard_name # Latest version docs
/shards/:shard_name/:version # Specific version docs
/shards/:shard_name/:version/:path # Specific doc page
```

Acceptance Criteria

• Homepage lists all shards with documentation
• Search filters shard list correctly
• Documentation viewer renders HTML properly
• Version switcher shows available versions and switches correctly
• Navigation sidebar works (expand/collapse, links)
• Breadcrumbs show current location
• Links to GitHub source work
• Links to CrystalShards.org package page work
• Responsive design on mobile, tablet, desktop
• MUST verify with Playwright MCP after implementation (see CLAUDE.md section 12)

UI/UX Verification Required

After implementation, verify using Playwright MCP:

• Navigate to https://crystaldocs.org
• Check accessibility snapshot
• Test shard search functionality
• Click on a shard to view docs
• Test version switcher
• Test navigation sidebar
• Verify links work (GitHub, CrystalShards)
• Check responsive design
• Verify no console errors

Priority

HIGH - Core functionality for CrystalDocs.org (priority app #2)

Application

CrystalDocs.org