feat(docs): enhance documentation readability and structure

docs/_config.yml

@@ -1,13 +1,82 @@
 title: Hapax
-description: Large Language Model Infrastructure, Simplified
+description: The reliability layer between your code and LLM providers
 remote_theme: just-the-docs/just-the-docs
 
+# Theme and Navigation
 color_scheme: dark
+nav_spacing: normal
+heading_anchors: true
+back_to_top: true
+back_to_top_text: "Back to top"
 
+# Custom Styles
+custom_css: true
+custom_css_path: "/assets/css/custom.css"
+
+# Typography and Spacing
+spacing_unit: 1.5
+font_size: 16px
+content_width: "1000px"
+typographic_spacing: true
+
+# Heading Styles
+heading_spacing: 1.5
+h1_size: 2.5rem
+h2_size: 2rem
+h3_size: 1.5rem
+h4_size: 1.25rem
+
+# Text Styles
+body_line_height: 1.6
+body_font_family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif
+mono_font_family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace
+
+# Search Configuration
 search_enabled: true
+search:
+  heading_level: 2
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 5
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: false
 
+# Code and Content
+enable_copy_code_button: true
+code_block_padding: 1rem
+code_font_size: 0.9em
+
+# Callouts for Important Information
+callouts:
+  note:
+    title: Note
+    color: blue
+  important:
+    title: Important
+    color: purple
+  warning:
+    title: Warning
+    color: red
+  tip:
+    title: Tip
+    color: green
+  security:
+    title: Security
+    color: yellow
+
+# External Links
 aux_links:
-  "Hapax on GitHub":
+  "GitHub":
     - "//github.com/teilomillet/hapax"
+aux_links_new_tab: true
+
+# License
+footer_content: "Licensed under Apache License, Version 2.0."
 
-aux_links_new_tab: true
+# Additional Styles
+callouts_opacity: 0.9
+callouts_padding: 1rem
+table_font_size: 0.9em
+nav_font_size: 1rem
+sidebar_width: "300px"

docs/assets/css/custom.css

@@ -0,0 +1,96 @@
+/* Typography Enhancements */
+.main-content {
+    font-size: var(--font-size, 16px);
+    line-height: var(--body-line-height, 1.6);
+}
+
+/* Heading Styles */
+.main-content h1 {
+    margin-top: 2em;
+    margin-bottom: 1em;
+    font-weight: 500;
+    letter-spacing: -0.5px;
+}
+
+.main-content h2 {
+    margin-top: 1.5em;
+    margin-bottom: 0.75em;
+    font-weight: 500;
+    border-bottom: 1px solid var(--border-color);
+    padding-bottom: 0.3em;
+}
+
+.main-content h3 {
+    margin-top: 1.2em;
+    margin-bottom: 0.5em;
+    font-weight: 500;
+}
+
+/* Code Blocks */
+.highlight {
+    margin: 1.5em 0;
+    border-radius: 4px;
+}
+
+.highlight pre {
+    padding: var(--code-block-padding, 1rem);
+    font-family: var(--mono-font-family);
+    font-size: var(--code-font-size, 0.9em);
+}
+
+/* Callouts */
+.callout {
+    margin: 1.5em 0;
+    padding: var(--callouts-padding, 1rem);
+    border-radius: 4px;
+    opacity: var(--callouts-opacity, 0.9);
+}
+
+.callout p:last-child {
+    margin-bottom: 0;
+}
+
+/* Lists */
+.main-content ul,
+.main-content ol {
+    margin: 0.8em 0;
+    padding-left: 1.5em;
+}
+
+.main-content li {
+    margin: 0.3em 0;
+}
+
+/* Links */
+.main-content a {
+    text-decoration: none;
+    border-bottom: 1px solid var(--link-color);
+}
+
+.main-content a:hover {
+    border-bottom-width: 2px;
+}
+
+/* Tables */
+.main-content table {
+    margin: 1.5em 0;
+    font-size: var(--table-font-size, 0.9em);
+    box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+}
+
+/* Navigation */
+.nav-list .nav-list-item {
+    font-size: var(--nav-font-size, 1rem);
+    margin: 0.3em 0;
+}
+
+/* Search Results */
+.search-result-doc {
+    font-size: 1.1em;
+    margin-bottom: 0.5em;
+}
+
+.search-result-preview {
+    color: var(--text-color);
+    opacity: 0.8;
+} 

docs/getting-started/5-minute-setup.md

@@ -0,0 +1,44 @@
+---
+layout: page
+title: 5-Minute Setup
+parent: Getting Started
+nav_order: 1
+---
+
+# 5-Minute Setup
+
+This guide will get you running with Hapax in under 5 minutes using Docker.
+
+{: .note }
+> **Prerequisites**
+> - Docker installed
+> - API key from any supported provider (OpenAI, Anthropic, etc.)
+
+## 1. Run Hapax
+
+Copy and run this command, replacing `your_key` with your API key:
+
+```bash
+docker run -p 8080:8080 \
+  -e OPENAI_API_KEY=your_key \
+  teilomillet/hapax:latest
+```
+
+## 2. Verify Installation
+
+Test that Hapax is running:
+
+```bash
+curl http://localhost:8080/health
+# Expected: {"status":"ok"}
+```
+
+## 3. Make Your First Request
+
+Send a test completion request:
+
+```bash
+curl -X POST http://localhost:8080/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"Hello"}]}'
+```

docs/getting-started/index.md

@@ -0,0 +1,31 @@
+---
+layout: page
+title: Getting Started
+nav_order: 2
+has_children: true
+---
+
+# Getting Started with Hapax
+
+Choose your path to get started with Hapax:
+
+{: .note }
+> **New to Hapax?**  
+> Start with our [5-Minute Setup](5-minute-setup) guide to get running quickly.
+
+## Installation Options
+
+1. **[5-Minute Setup](5-minute-setup)**
+   - Fastest path to running Hapax
+   - Uses Docker
+   - Minimal configuration needed
+
+2. **[Manual Installation](manual-installation)**
+   - Full control over installation
+   - Suitable for development
+   - Access to all features
+
+3. **[Production Setup](../production)**
+   - Secure deployment configuration
+   - Monitoring setup
+   - Performance optimization 

docs/index.md

@@ -6,11 +6,67 @@ nav_order: 1
 
 # Hapax Documentation
 
-Large Language Model Infrastructure, Simplified
+{: .fs-9 }
+The reliability layer between your code and LLM providers
 
-## What is Hapax?
+{: .fs-6 .fw-300 }
+A lightweight, production-ready infrastructure layer that ensures continuous operation through intelligent provider management and automatic failover.
 
-Building with Large Language Models is complex. Multiple providers, varying APIs, inconsistent performance, unpredictable costs—these challenges consume more engineering time than the actual innovation.
+[Quick Start](getting-started/5-minute-setup){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
+[View Source](https://github.com/teilomillet/hapax){: .btn .fs-5 .mb-4 .mb-md-0 }
 
-[Get Started](getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
-[View on GitHub](https://github.com/teilomillet/hapax){: .btn .fs-5 .mb-4 .mb-md-0 }
+---
+
+## Why Hapax?
+
+{: .important }
+> Hapax addresses the fundamental challenges of working with LLM providers: service reliability, provider management, and operational visibility.
+
+### Key Benefits
+
+{: .note }
+> **Continuous Operation**  
+> Automatic failover between providers maintains service availability during outages or degraded performance.
+
+{: .note }
+> **Minimal Configuration**  
+> Single configuration file handles all provider settings, health checks, and failover logic.
+
+{: .note }
+> **Operational Insight**  
+> Built-in metrics expose detailed provider performance, request patterns, and system health.
+
+## Core Features
+
+### Intelligent Provider Management
+- Health monitoring with configurable thresholds
+- Automatic provider failover
+- Circuit breaker implementation
+- Request deduplication
+
+### System Architecture
+- Request routing and load distribution
+- Comprehensive error handling
+- Structured logging with request tracing
+- HTTP/3 support
+
+### Security and Monitoring
+- API key-based authentication
+- Request validation
+- Usage metrics per endpoint
+- Prometheus integration
+
+## Documentation
+
+- [Quick Start](getting-started/5-minute-setup)
+- [Core Features](core-features)
+- [Production Setup](production)
+- [API Reference](api)
+
+## Development
+
+Find issues or want to contribute?
+- [Source Code](https://github.com/teilomillet/hapax)
+- [Issue Tracker](https://github.com/teilomillet/hapax/issues)
+- [Security Guide](production/security)
+- [Configuration Reference](getting-started/configuration)