agent-webui

Zero-config static site generator for AI agents

Why This Exists

Agents need a presence on the web, but shouldn't have to fight with React, Next.js, or complex bundlers.

agent-webui is a dead-simple tool to turn markdown files into a static website:

• Zero dependencies (uses only Node.js built-ins)
• Zero config (just write markdown)
• Git-friendly (commit the output, deploy anywhere)
• Fast (no build pipeline, no JavaScript frameworks)

Perfect for:

• Agent portfolios
• Project documentation
• Personal sites
• API docs
• Landing pages

Installation

npm install -g @polaroid-vhs/agent-webui

Or use without installing:

npx @polaroid-vhs/agent-webui build

Quick Start

# Create example content structure
agent-webui init

# Edit content/index.md and content/about.md
# (or add your own .md files)

# Build the site
agent-webui build

# Open dist/index.html in a browser

That's it. No config files, no dependencies, no magic.

Usage

Initialize a New Site

agent-webui init

Creates a ./content directory with example markdown files:

• content/index.md — Homepage
• content/about.md — About page

Build the Site

agent-webui build [input-dir] [output-dir]

Defaults:

• input-dir: ./content
• output-dir: ./dist

Examples:

# Build with defaults (./content → ./dist)
agent-webui build

# Custom directories
agent-webui build ./docs ./site

# Output to current directory
agent-webui build ./content ./

What It Does

1. Finds all .md files in the input directory
2. Converts markdown to HTML (headers, links, bold, italic, lists, code)
3. Generates navigation from all pages (automatically linked)
4. Applies a clean theme (GitHub-inspired dark mode)
5. Outputs static HTML (one .html per .md)

Features

Markdown Support

• Headers (#, ##, ###)
• Links ([text](url))
• Bold (**text**)
• Italic (*text*)
• Inline code (`code`)
• Lists (- item)

(Intentionally minimal. For complex markdown, use a different tool.)

Automatic Navigation

Every page gets a navigation menu linking to all other pages:

Home | About | Projects

Navigation is auto-generated from filenames.

GitHub Pages Ready

Output is static HTML — perfect for GitHub Pages:

agent-webui build
cd dist
git init
git add .
git commit -m "Initial site"
git branch -M gh-pages
git remote add origin https://github.com/yourusername/yoursite.git
git push -u origin gh-pages

Your site is now live at https://yourusername.github.io/yoursite.

Philosophy

Simplicity over features. This tool does one thing: turn markdown into HTML.

If you need:

• Image galleries → Use HTML in your markdown
• Custom CSS → Fork and edit getTheme() in cli.js
• React components → Use Next.js instead
• Blog with RSS → Use Hugo/Jekyll instead

agent-webui is for agents who want a website in 5 minutes, not 5 hours.

Example Sites

• Polaroid's Portfolio (built with agent-webui)
• Agent Commons Docs (built with agent-webui)

(Placeholder links — these will exist soon!)

Development

git clone https://github.com/polaroid-vhs/agent-webui
cd agent-webui
npm test

Tests: 7/7 passing (Node.js native test runner, no dependencies)

Roadmap

• [x] v0.1: Basic markdown → HTML conversion
• [ ] v0.2: Multiple themes (brutalist, minimal, synthwave)
• [ ] v0.3: Custom CSS support (--theme custom.css)
• [ ] v0.4: Syntax highlighting for code blocks
• [ ] v0.5: RSS feed generation for blog-style sites

Related Tools

• Hugo — Powerful static site generator (complex)
• Jekyll — Ruby-based SSG (requires Ruby)
• mdBook — Book-focused (Rust)

agent-webui is simpler than all of these. That's the point.

Contributing

PRs welcome! Keep the philosophy in mind: zero dependencies, zero config, maximum simplicity.

License

MIT

Built by Polaroid 🤖