feat: full site

README.md

@@ -1,8 +1,8 @@
 # ivuorinen/homebrew-tap
 
-A Homebrew tap for ivuorinen's custom formulae with automated documentation.
+A Homebrew tap for ivuorinen's custom formulae with automated documentation and dark mode support.
 
-## Usage
+## Quick Start
 
 ```bash
 # Add the tap
@@ -17,38 +17,156 @@ brew search ivuorinen/homebrew-tap/
 
 ## Documentation
 
-Visit [https://ivuorinen.github.io/homebrew-tap/](https://ivuorinen.github.io/homebrew-tap/) for complete documentation of all available formulae.
-
-## Available Formulae
-
-The documentation is automatically generated from the formula files and includes:
-- Installation instructions
-- Dependencies
-- Version information
-- Source links
+Visit [https://ivuorinen.net/homebrew-tap/](https://ivuorinen.net/homebrew-tap/) for complete documentation with:
+- Installation instructions for each formula
+- Dependencies and version information
+- Source links and SHA256 checksums
+- Dark mode support with system preference detection
 
 ## Contributing
 
 1. Fork this repository
-2. Create a new formula in the `Formula/` directory
-3. Follow the [Homebrew Formula Cookbook](https://docs.brew.sh/Formula-Cookbook)
-4. Submit a pull request
+2. Create a new formula in the `Formula/` directory following the [Homebrew Formula Cookbook](https://docs.brew.sh/Formula-Cookbook)
+3. Submit a pull request
 
-The CI will automatically validate your formula and update the documentation.
+The CI will automatically validate your formula and update the documentation site.
 
 ## Development
 
+This tap uses a custom Ruby-based static site generator with zero external dependencies.
+
+### Commands
+
+#### Using Make (Recommended)
+
+The project includes a comprehensive Makefile that provides convenient commands for all build operations:
+
 ```bash
-# Install dependencies
-bundle install
-
-# Parse formulae locally
-ruby scripts/parse_formulas.rb
-
-# Serve documentation locally
-cd docs && bundle exec jekyll serve
+make help     # Show all available commands with descriptions
+make build    # Build the documentation site
+make serve    # Start development server (http://localhost:4000)
+make parse    # Parse formulae and generate JSON data only
+make clean    # Clean all generated files
 ```
 
+**Development workflow:**
+```bash
+make dev           # Full development workflow (parse + build + serve)
+make setup         # Check development environment setup
+make test          # Run validation tests
+make check         # Check project structure
+make install       # Install Ruby dependencies (if Gemfile exists)
+make info          # Show project information
+```
+
+**Server options:**
+```bash
+make serve PORT=3000              # Use port 3000
+make serve HOST=0.0.0.0          # Bind to all interfaces
+make serve PORT=8080 HOST=0.0.0.0 # Custom port and host
+make serve-all                   # Start server on all interfaces (0.0.0.0)
+make serve-3000                  # Quick shortcut for port 3000
+make watch                       # Alias for serve with auto-rebuild
+```
+
+**Homebrew-specific targets:**
+```bash
+make tap-test                    # Test tap installation locally
+make tap-install                 # Install this tap locally
+make formula-new NAME=tool-name  # Create new formula template
+```
+
+**Production and testing:**
+```bash
+make build-production  # Clean build for production deployment
+make version          # Show version information
+```
+
+All Makefile targets include helpful status messages and error handling.
+
+**File Watching and Auto-Rebuild:**
+
+The development server (`make serve`) includes intelligent file watching that:
+- ✅ Only watches source files (Formula/, theme/, scripts/, config files)
+- ✅ Excludes generated output files to prevent infinite rebuild loops
+- ✅ Includes debouncing to handle multiple rapid file changes
+- ✅ Provides clear status messages for rebuild operations
+
+Files monitored for changes:
+- `Formula/**/*.rb` - Homebrew formula files
+- `theme/**/*.{css,js,erb,html}` - Theme templates and assets
+- `scripts/*.rb` - Build scripts
+- `Makefile`, `README.md`, `Gemfile` - Configuration files
+
+#### Using Ruby Scripts (Alternative)
+
+```bash
+ruby scripts/make.rb build    # Build the documentation site
+ruby scripts/make.rb serve    # Start development server
+ruby scripts/make.rb parse    # Parse formulae and generate JSON data only
+ruby scripts/make.rb clean    # Clean all generated files
+ruby scripts/make.rb help     # Show all available commands
+```
+
+### How It Works
+
+The documentation system consists of three main components:
+
+1. **Formula Parser** - Safely extracts metadata from `.rb` files using regex patterns (no code evaluation)
+2. **Site Builder** - Generates static HTML from ERB templates using the parsed data
+3. **Development Server** - Serves the site locally with auto-rebuild on file changes
+
+### Project Structure
+
+```
+docs/
+├── _data/                  # Generated JSON data
+├── assets/                 # Copied static assets (fonts, images, etc.)
+├── formula/                # Individual formula pages (generated)
+├── index.html              # Homepage (generated)
+└── formulae.html           # Formula listing (generated)
+theme/
+├── assets/                 # Original assets: fonts, images, etc.
+├── _command_input.html.erb # Input command snippet partial
+├── _footer.html.erb        # Footer partial
+├── _formula_card.html.erb  # Formula card partial
+├── _head.html.erb          # HTML head partial
+├── _header.html.erb        # Header partial
+├── _nav.html.erb           # Navigation partial
+├── _nothing_here.html.erb  # "No formulae found" partial
+├── index.html.erb          # Homepage template
+├── formulae.html.erb       # Formula listing template
+├── formula.html.erb        # Individual formula template
+├── style.css               # Stylesheets with dark mode support
+└── main.js                 # Site functionality: search, dark mode toggle, etc.
+Formula/
+└── *.rb                    # Homebrew formula files
+scripts/
+├── make.rb                 # Main build script
+└── parser.rb               # Formula parser
+Makefile                    # Build commands and targets
+README.md                   # This documentation
+Gemfile                     # Ruby dependencies
+```
+
+### Features
+
+- ✅ Zero external dependencies (Ruby stdlib only)
+- ✅ Fast builds with auto-reload development server
+- ✅ Dark mode with system preference detection
+- ✅ Responsive design with accessibility support
+- ✅ GitHub Pages compatible output
+- ✅ Automatic deployment via GitHub Actions
+
+### Customization
+
+Templates can be customized by editing files in the `theme/` directory:
+- `index.html.erb` - Homepage template
+- `formulae.html.erb` - Formula listing page
+- `formula.html.erb` - Individual formula page template
+- `style.css` - Stylesheets and theming
+- `main.js` - JavaScript functionality
+
 ## License
 
 This tap is released under the MIT License. See LICENSE for details.