+
+
+
+
diff --git a/scripts/build_microsite.py b/scripts/build_microsite.py
new file mode 100755
index 0000000..fece709
--- /dev/null
+++ b/scripts/build_microsite.py
@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Build script for the BadgeSort microsite.
+
+This script generates the microsite HTML by combining:
+1. The HTML/CSS/JS template from docs/index.template.html
+2. The commit hash for display
+
+The microsite Python code is kept separate from the CLI to handle browser-specific functionality.
+"""
+
+import sys
+import subprocess
+from pathlib import Path
+
+
+def build_microsite(repo_root, commit_hash):
+ """Build the microsite HTML file by injecting the commit hash."""
+ repo_path = Path(repo_root)
+
+ # Read the template
+ template_path = repo_path / 'docs' / 'index.template.html'
+ with open(template_path, 'r', encoding='utf-8') as f:
+ template = f.read()
+
+ # Replace commit hash placeholder
+ html_content = template.replace('{{COMMIT_HASH}}', commit_hash[:8])
+
+ # Write the output
+ output_path = repo_path / 'docs' / 'index.html'
+ with open(output_path, 'w', encoding='utf-8') as f:
+ f.write(html_content)
+
+ print(f"Microsite built successfully!")
+ print(f" Template: {template_path}")
+ print(f" Output: {output_path}")
+ print(f" Commit: {commit_hash[:8]}")
+
+
+def main():
+ """Main entry point for the build script."""
+ # Get the repo root (parent of scripts directory)
+ script_dir = Path(__file__).parent
+ repo_root = script_dir.parent
+
+ # Get the current commit hash
+ try:
+ result = subprocess.run(
+ ['git', 'rev-parse', 'HEAD'],
+ cwd=repo_root,
+ capture_output=True,
+ text=True,
+ check=True
+ )
+ commit_hash = result.stdout.strip()
+ except subprocess.CalledProcessError:
+ print("Warning: Could not get git commit hash, using 'unknown'")
+ commit_hash = 'unknown'
+
+ # Build the microsite
+ build_microsite(repo_root, commit_hash)
+
+
+if __name__ == '__main__':
+ main()
From 70249622bec2672e940ed78a2188216bf0f3bce5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 28 Oct 2025 21:44:15 +0000
Subject: [PATCH 3/5] docs: Update README and add build system documentation
- Update main README.md with live site link and build info
- Add comprehensive BUILD_SYSTEM.md documentation
- Document the automated build and deployment process
Co-authored-by: ChipWolf <3164166+ChipWolf@users.noreply.github.com>
---
README.md | 4 +-
docs/BUILD_SYSTEM.md | 215 +++++++++++++++++++++++++++++++++++++++++++
docs/index.html | 2 +-
3 files changed, 219 insertions(+), 2 deletions(-)
create mode 100644 docs/BUILD_SYSTEM.md
diff --git a/README.md b/README.md
index 8afa8f8..eda65de 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,9 @@
## 🎨 Interactive Generator
-**New!** Try the [interactive web-based generator](./docs/) to visually configure and generate your BadgeSort YAML! No installation required - just select your badges, configure the options, and copy the generated GitHub Actions YAML.
+**New!** Try the [interactive web-based generator](https://chipwolf.github.io/BadgeSort/) to visually configure and generate your BadgeSort YAML! No installation required - just select your badges, configure the options, and copy the generated GitHub Actions YAML. The live site is automatically deployed from the latest code and displays the build commit hash.
+
+For local development of the microsite, see [docs/README.md](./docs/README.md).
## Background:
diff --git a/docs/BUILD_SYSTEM.md b/docs/BUILD_SYSTEM.md
new file mode 100644
index 0000000..433a740
--- /dev/null
+++ b/docs/BUILD_SYSTEM.md
@@ -0,0 +1,215 @@
+# Microsite Build and Deployment System
+
+## Summary
+
+This document describes the automated build and deployment system for the BadgeSort microsite.
+
+## Problem
+
+Previously, the BadgeSort microsite at `/docs/index.html` contained a complete copy of the application code embedded directly in the HTML file. When the main BadgeSort application was updated, the microsite needed to be manually synchronized, leading to:
+
+- Code duplication
+- Maintenance burden
+- Risk of the microsite falling out of sync with the main application
+
+## Solution
+
+An automated build and deployment system that:
+
+1. **Separates template from generated output**: The microsite source is now in `docs/index.template.html` with a placeholder for dynamic content (commit hash)
+2. **Automates the build**: A Python script (`scripts/build_microsite.py`) generates the final `docs/index.html` by injecting the current commit hash
+3. **Automates deployment**: A GitHub Actions workflow (`.github/workflows/deploy-pages.yml`) builds and deploys the microsite to GitHub Pages automatically
+4. **Displays build information**: The deployed site shows the commit hash it was built from
+
+## Architecture
+
+### Files
+
+- **`docs/index.template.html`** (source, tracked in git)
+ - Contains the complete microsite HTML, CSS, JavaScript, and PyScript code
+ - Includes placeholder `{{COMMIT_HASH}}` for build information
+ - This is the file to edit when making changes to the microsite
+
+- **`docs/index.html`** (generated, NOT tracked in git)
+ - Generated from the template by `scripts/build_microsite.py`
+ - Has the commit hash placeholder replaced with the actual git commit hash
+ - Excluded from version control via `.gitignore`
+
+- **`scripts/build_microsite.py`**
+ - Python script that builds the microsite
+ - Reads `docs/index.template.html`
+ - Injects the current git commit hash
+ - Writes to `docs/index.html`
+
+- **`.github/workflows/deploy-pages.yml`**
+ - GitHub Actions workflow for automated deployment
+ - Triggered on push to `main` branch when relevant files change
+ - Can also be manually triggered via workflow_dispatch
+ - Builds the microsite and deploys to GitHub Pages
+
+### Build Process
+
+```
+┌─────────────────────────┐
+│ docs/index.template.html│
+│ (source with {{...}}) │
+└───────────┬─────────────┘
+ │
+ ▼
+┌─────────────────────────┐
+│ scripts/build_microsite.py│
+│ - Get git commit hash │
+│ - Replace placeholders │
+└───────────┬─────────────┘
+ │
+ ▼
+┌─────────────────────────┐
+│ docs/index.html │
+│ (generated output) │
+└─────────────────────────┘
+```
+
+### Deployment Process
+
+```
+┌─────────────────────────┐
+│ Push to main branch │
+│ (docs/**, badgesort/** │
+│ or build scripts) │
+└───────────┬─────────────┘
+ │
+ ▼
+┌─────────────────────────┐
+│ GitHub Actions │
+│ deploy-pages.yml │
+│ 1. Checkout code │
+│ 2. Setup Python │
+│ 3. Build microsite │
+│ 4. Configure Pages │
+│ 5. Upload artifact │
+│ 6. Deploy to Pages │
+└───────────┬─────────────┘
+ │
+ ▼
+┌─────────────────────────┐
+│ GitHub Pages │
+│ https://chipwolf. │
+│ github.io/BadgeSort/ │
+└─────────────────────────┘
+```
+
+## Usage
+
+### Making Changes to the Microsite
+
+1. Edit `docs/index.template.html`
+2. Test locally:
+ ```bash
+ python3 scripts/build_microsite.py
+ cd docs && python3 -m http.server 8000
+ ```
+3. Commit and push to `main` branch
+4. GitHub Actions will automatically build and deploy
+
+### Local Development
+
+```bash
+# Build the microsite
+python3 scripts/build_microsite.py
+
+# Serve locally
+cd docs && python3 -m http.server 8000
+# Visit http://localhost:8000/
+```
+
+### Manual Deployment
+
+If needed, the workflow can be manually triggered:
+1. Go to the repository's Actions tab
+2. Select "Deploy GitHub Pages" workflow
+3. Click "Run workflow"
+4. Select the branch (usually `main`)
+5. Click "Run workflow"
+
+## Code Maintenance
+
+### Microsite vs CLI Code
+
+The microsite Python code (embedded in `docs/index.template.html`) is a **browser-adapted version** of the BadgeSort CLI logic. Key differences:
+
+- **Microsite**: Uses PyScript, DOM manipulation, JavaScript interop
+- **CLI**: Uses standard Python libraries, file I/O, CLI arguments
+
+When updating badge generation or sorting algorithms:
+1. Update `badgesort/icons.py` for CLI functionality
+2. Update the corresponding code in `docs/index.template.html` for the microsite
+3. Both implementations should be kept conceptually in sync
+
+The microsite is not automatically generated from the CLI code because:
+- Different execution environments (browser vs Python interpreter)
+- Different interfaces (DOM vs command-line)
+- Different dependencies (PyScript vs system packages)
+
+## Benefits
+
+1. **No manual synchronization**: Deployment is fully automated
+2. **Version transparency**: Build commit hash visible on the site
+3. **Consistent deployments**: Every push to main triggers rebuild
+4. **Easy rollback**: Can redeploy any previous commit
+5. **Clear separation**: Template vs generated file
+6. **No code in git**: Generated file excluded from version control
+
+## Configuration
+
+### GitHub Repository Settings
+
+For the workflow to work, ensure:
+
+1. **GitHub Pages is enabled**:
+ - Go to Settings → Pages
+ - Source: GitHub Actions (not branch-based deployment)
+
+2. **Workflow permissions**:
+ - Go to Settings → Actions → General
+ - Workflow permissions: "Read and write permissions"
+ - Allow GitHub Actions to create and approve pull requests: Enabled
+
+### Workflow Triggers
+
+The workflow triggers on:
+- Push to `main` branch when these paths change:
+ - `docs/**`
+ - `badgesort/**`
+ - `scripts/build_microsite.py`
+ - `.github/workflows/deploy-pages.yml`
+- Manual trigger via `workflow_dispatch`
+
+## Troubleshooting
+
+### Build fails with "Could not get git commit hash"
+
+This shouldn't happen in GitHub Actions (git is always available), but if running locally in a non-git directory, the script will use "unknown" as the commit hash.
+
+### Page not updating after push
+
+1. Check the Actions tab for workflow runs
+2. Verify the workflow completed successfully
+3. GitHub Pages may cache content - wait a few minutes or force refresh (Ctrl+F5)
+4. Check that the workflow triggers are configured correctly
+
+### Local build fails
+
+Ensure you're running from the repository root:
+```bash
+python3 scripts/build_microsite.py
+```
+
+## Future Enhancements
+
+Possible future improvements:
+
+1. **Minification**: Add HTML/CSS/JS minification to reduce file size
+2. **Asset optimization**: Optimize any images or assets
+3. **Build caching**: Cache build artifacts for faster deployments
+4. **Preview deployments**: Deploy PR previews for testing changes
+5. **Code extraction**: Extract shared algorithm logic into a common module that both CLI and microsite can import (would require PyScript package support)
diff --git a/docs/index.html b/docs/index.html
index bdf33c7..880ef93 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -465,7 +465,7 @@
From 66dc8382ed135d690af2577dcc949438dc73f63e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 28 Oct 2025 21:46:33 +0000
Subject: [PATCH 4/5] fix: Remove generated index.html from version control and
improve docs
- Remove docs/index.html from git tracking (it's generated during deployment)
- Add detailed checklist for keeping CLI and microsite code in sync
- Improve BUILD_SYSTEM.md with specific guidance on maintaining consistency
Co-authored-by: ChipWolf <3164166+ChipWolf@users.noreply.github.com>
---
docs/BUILD_SYSTEM.md | 27 +
docs/index.html | 1367 ------------------------------------------
2 files changed, 27 insertions(+), 1367 deletions(-)
delete mode 100644 docs/index.html
diff --git a/docs/BUILD_SYSTEM.md b/docs/BUILD_SYSTEM.md
index 433a740..485c391 100644
--- a/docs/BUILD_SYSTEM.md
+++ b/docs/BUILD_SYSTEM.md
@@ -150,6 +150,33 @@ The microsite is not automatically generated from the CLI code because:
- Different interfaces (DOM vs command-line)
- Different dependencies (PyScript vs system packages)
+### Keeping Code in Sync
+
+When making changes to badge generation or sorting algorithms, follow this checklist:
+
+**For CLI Changes** (`badgesort/icons.py`):
+- [ ] Update the CLI function (e.g., `run()`, sorting algorithms, badge URL generation)
+- [ ] Test the CLI locally: `python -m badgesort.icons -s github python`
+- [ ] Update corresponding logic in `docs/index.template.html` (see checklist below)
+
+**For Microsite Changes** (`docs/index.template.html`):
+- [ ] Locate the equivalent function in the embedded Python code (after line 637)
+- [ ] Update the logic to match the CLI changes
+- [ ] Account for browser-specific differences (PyScript, no file I/O, DOM updates)
+- [ ] Test locally: `python3 scripts/build_microsite.py && cd docs && python3 -m http.server`
+- [ ] Verify in browser at http://localhost:8000/
+
+**Key Areas to Keep in Sync**:
+1. **Badge URL generation**: Search for `icon_url =` in both files
+2. **Sorting algorithms**: Functions `Hilbert_to_int`, `lum`, `step`, color sort logic
+3. **SVG embedding logic**: `svg_to_base64_data_uri` and related functions
+4. **Color calculations**: RGB to HSV, brightness calculations, logo color selection
+
+**Testing Both**:
+- [ ] CLI: Run with various options and verify output
+- [ ] Microsite: Test all sorting algorithms, badge styles, and providers
+- [ ] Compare badge URLs generated by both (should be identical for same inputs)
+
## Benefits
1. **No manual synchronization**: Deployment is fully automated
diff --git a/docs/index.html b/docs/index.html
deleted file mode 100644
index 880ef93..0000000
--- a/docs/index.html
+++ /dev/null
@@ -1,1367 +0,0 @@
-
-
-
-
-
- BadgeSort - Interactive Badge Generator
-
-
-
-
-
-
-