athola HTML Portal Generator
Convert any codebase into a single, self-contained HTML portal application. The output is one .html file with embedded styles, scripts, and data that works offline, on file:// protocol, and can be uploaded into AI application portals.
When to Use
- You have a codebase (CLI tool, library, API, framework) and need an interactive HTML representation of its functionality
- The HTML will be uploaded into a smart AI portal or application integration system
- You need all features to work standalone without a running server
- You want users to explore, validate, analyze, and interact with the product from a browser
Process
Follow these phases in order. Each phase builds on the previous.
Phase 1: Codebase Analysis
Understand what the product does before writing any HTML.
- Read project documentation: README, CLAUDE.md, architecture docs, changelogs
- Identify core crates/packages: Map each module's purpose and public API
- Catalog user-facing features: CLI commands, API endpoints, configuration options
- Extract data structures: Response types, configuration schemas, enum values
- Find existing UI code: Dashboards, templates, stylesheets (reuse their design language)
Produce a mental inventory:
- Feature list (what the product does)
- Data catalog (what entities/types exist)
- Command/API reference (how users interact)
- Visual identity (colors, fonts, layout patterns from existing UI)
Phase 2: Reference Analysis (if provided)
If the user provides a reference HTML app:
- Read the first and last ~3KB to understand structure (large files may be minified)
- Identify the design pattern: CSS variables, layout system, component structure
- Note the interaction model: controls bar, status bar, grid layout, tab navigation
- Extract the color palette and typography from CSS custom properties
Phase 3: Architecture Design
Design the portal as a single-page app with tab navigation.
Required structural elements:
- Sticky header with product name, version badge, and summary stats
- Tab navigation bar for switching between views
- Main container with
max-widthfor readability - Sticky status bar footer with links to docs/repo
- Toast notification system for user feedback
View planning - map each product feature to a view:
| Feature Type | View Pattern |
|---|---|
| Entity browsing (skills, packages, endpoints) | Card grid with search/filter/sort and detail panel |
| Validation/checking | Split editor (textarea input) and results panel |
| Analysis/metrics | Input, stat cards, and bar charts |
| Configuration/creation | Form inputs, live preview, and download |
| Format conversion | Side-by-side input/output with target selector |
| Reference docs (commands, APIs) | Searchable/filterable list with copy-on-click |
| Status/compatibility | Matrix grid or table |
| Dashboard/overview | Stat cards, quick actions, and recent items |
Every view must work 100% standalone. No external API calls required. Embed demo data. Add optional live-server connection as a bonus.
Phase 4: Data Embedding
Convert real product data into JavaScript arrays embedded in the HTML.
- Scan the actual codebase for entities (skills, commands, endpoints, types)
- Extract metadata from source files (frontmatter, doc comments, type definitions)
- Generate realistic validation states based on actual product rules
- Include failure reasons as tooltip/detail text so users understand why things pass/fail
- Store as
constarrays in the<script>block - no external JSON files
For large datasets (100+ items), use a build script to extract and format the data rather than hand-writing it.
If the product has local files users might want to scan:
- Add a "Scan Local" button using the File System Access API (
showDirectoryPicker) - Walk directories recursively, parse file frontmatter/headers
- Replace the embedded data with live-scanned results
- Store full file content on scanned items for downstream analysis
Phase 5: Implementation
Build the HTML file following these rules:
Single-file architecture:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Product - Portal</title>
<style>/* All CSS here */</style>
</head>
<body>
<!-- All HTML here -->
<script>/* All JS here, wrapped in IIFE */</script>
</body>
</html>
CSS requirements:
- Use CSS custom properties (
:root { --bg: ...; }) for theming - Support dark mode (default) and light mode via
@media (prefers-color-scheme: light) - Reuse the product's existing color palette if it has one
- Mobile-responsive with
@media (max-width: ...)breakpoints - Style scrollbars, focus states, and transitions
JavaScript requirements:
- Wrap everything in an IIFE:
(function() { 'use strict'; ... })(); - No inline
onclickhandlers - useaddEventListenerexclusively - Clipboard operations must fall back to
document.execCommand('copy')forfile://protocol - Every click should produce visible feedback (toast, navigation, highlight)
- Autocomplete/datalist for name inputs that reference the embedded data
- Tab navigation via
data-viewattributes and.activeclass toggling
Interactivity checklist - every element the user can see must do something when clicked:
- Cards/list items: select, show detail, or navigate
- Buttons: perform action with toast feedback
- Reference items: copy to clipboard on click
- Status indicators: show tooltip with explanation on hover
- External links: open in new tab with
target="_blank" rel="noopener" - Quick actions: run in-browser if possible, otherwise copy CLI command and link to docs
Phase 6: Feature Implementation Patterns
Entity Browser (the main catalog view):
- Search input (filters by name and description)
- Source/category dropdown filter
- Quality/status dropdown filter
- Sort selector (alpha, by source, by status)
- Card grid with: name, source badge, description, validation tags
- Validation tags with hover tooltips showing failure reasons
- Detail panel (sticky sidebar) with full metadata on click
- Export button (download as JSON)
- Local scan button (File System Access API)
Validator:
- Target selector (individual CLI or "All")
- Textarea for pasting content
- Validate button - runs client-side validation logic
- Autofix button - actually modifies content:
- Fills missing frontmatter fields
- Converts names to kebab-case
- Scaffolds body sections if too short
- Adds target-specific fields (e.g., globs for Cursor)
- Quality score panel (0-100 with visual ring)
- Download button for the validated/fixed file
- Load Sample button with realistic example content
Token/Size Analyzer:
- Name input with datalist autocomplete from catalog
- Load button to pull content from catalog by name
- Textarea for content
- Stat cards: tokens, words, lines, characters
- Progress bar with percentage (label outside bar for small values)
- Size category with color coding
- Optimization suggestions list
Format Converter:
- Source format selector
- Target format selector
- Convert button (single target)
- Convert All button (generates all formats with tab switcher)
- Download button
- Side-by-side input/output layout
Creator/Builder:
- Form fields for metadata (name, description, version, deps)
- Target-specific fields shown/hidden based on selection
- Body textarea with placeholder template
- Live preview panel (pre element)
- File path display showing where to save for each CLI
- Dependency graph visualization
- Download and Send-to-Validator buttons
Reference views (commands, tools, APIs):
- Search input
- Category filter
- Each item shows: name/command, description, usage guidance
- Click to copy, with toast confirmation
- Usage guidance paragraph below each item explaining when/how to use it
Dashboard:
- Stat cards row (total items, categories, etc.)
- Quick Actions panel:
- In-browser actions (green "runs here" badge): actually execute
- CLI-only actions (muted "CLI only" badge): copy command and link to docs
- Supporting info panels with clickable items
- Recent items grid linking to the browser view
Phase 7: Quality Checks
Before delivering, verify:
- JS syntax:
node -e "new Function(scriptContent)"parses without error - All tabs work: Each
data-viewhas a matchingid="view-..."element - No emdashes: Replace all
—with-(AI slop reduction) - No dead clicks: Every visible element does something on click
- Clipboard works on file://: All copy operations use the
execCommandfallback - Tooltips on status indicators: Hover explains why something passed/failed
- Responsive: Views stack on mobile
- Open in browser:
open filename.htmland manually test each tab
Phase 8: Iteration
The user will test and request changes. Common requests:
- "X doesn't do anything when I click it" - Add click handler with visible feedback
- "Information is missing" - Add data fields, tooltips, or guidance text
- "It should use my actual data" - Scan real files and embed or add local scan
- "Autofix doesn't change anything" - Make it fix more issues, scaffold content
- "The percentage doesn't show" - Move labels outside narrow bars
- "Link to docs" - Add
target="_blank"links to product documentation
Output
A single .html file (typically 60-120KB) that:
- Works by double-clicking in Finder/Explorer
- Works on
file://protocol in any browser - Optionally connects to a live server for real-time data
- Optionally scans local files via browser directory picker
- Can be uploaded directly into AI application portals