v0.2.1 release

docs/README.md

@@ -4,23 +4,28 @@ This directory contains auto-generated API documentation from LuaLS annotations.
 
 ## Files
 
+- **api.html** - Beautiful, searchable API documentation (2.2MB)
 - **index.html** - GitHub Pages landing page
-- **doc.md** - Markdown API reference (47,000+ lines)
-- **doc.json** - JSON API reference for tooling (11MB)
+- **build-docs.js** - Node.js script to convert markdown to HTML
+- **package.json** - Node.js dependencies for HTML generation
+- **.nojekyll** - Tells GitHub Pages to bypass Jekyll processing
+- **doc.md** - Raw markdown (gitignored, 960KB)
+- **doc.json** - Raw JSON (gitignored, 11MB)
 
 ## Regenerating Documentation
 
 To regenerate the documentation after making changes:
 
 ```bash
-./generate_docs.sh
+./scripts/generate_docs.sh
 ```
 
-Or manually:
-
-```bash
-lua-language-server --doc=. --doc_out_path=./docs
-```
+This will:
+1. Extract version from `FlexLove.lua` (single source of truth)
+2. Generate markdown from LuaLS annotations
+3. Convert to beautiful, searchable HTML with syntax highlighting
+4. Create navigation sidebar with search functionality
+5. Display version in page titles and headers
 
 ## Viewing Locally
 
@@ -66,4 +71,66 @@ The documentation is generated from LuaLS (Lua Language Server) annotations usin
 
 ## Requirements
 
-- lua-language-server (install via `brew install lua-language-server` on macOS)
+- **lua-language-server** - For generating markdown from annotations
+  - macOS: `brew install lua-language-server`
+  - Linux: See https://github.com/LuaLS/lua-language-server
+  
+- **Node.js** - For converting markdown to beautiful HTML
+  - macOS: `brew install node`
+  - Linux: Use your package manager or https://nodejs.org
+
+## Features
+
+The generated HTML documentation includes:
+- 🔍 **Live search** - Find classes and methods instantly
+- 📱 **Responsive design** - Works on all devices
+- 🌙 **Dark theme** - Easy on the eyes
+- 🎨 **Syntax highlighting** - Code examples are beautifully formatted
+- 🗂️ **Collapsible navigation** - Organized class/method structure
+- ⚡ **Fast** - Single-page application, no page reloads
+- 🎯 **Filtered** - Only user-facing classes, no internal implementation
+- 🏷️ **Versioned** - Auto-displays version from `FlexLove.lua`
+
+## Customizing Documentation
+
+Edit `doc-filter.js` to control which classes appear in the documentation:
+
+```javascript
+module.exports = {
+  // Whitelist mode: Only these classes will be included
+  include: [
+    'Animation',
+    'Color',
+    'Element',
+    'Theme',
+    // ... add more
+  ],
+  
+  // Blacklist mode: These classes will be excluded
+  exclude: [
+    'Context',
+    'Performance',
+    // ... add more
+  ],
+  
+  // Which mode to use
+  mode: 'whitelist'  // or 'blacklist'
+};
+```
+
+**Current filter:** Whitelist mode with 20 classes (down from 33)
+
+## Version Management
+
+The documentation automatically pulls the version from `FlexLove.lua`:
+
+```lua
+flexlove._VERSION = "0.2.0"  -- Single source of truth
+```
+
+To update the version:
+1. Change `_VERSION` in `FlexLove.lua`
+2. Run `./scripts/generate_docs.sh`
+3. Version appears in page titles, sidebar, and footer
+
+See `VERSIONING.md` for detailed version management workflow.