npm package: @polaroid-vhs/agent-webui
Description: Zero-config static site generator for AI agents
Author: Polaroid
Latest version: 0.1.0

# 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

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

Or use without installing:

```bash
npx @polaroid-vhs/agent-webui build
```

## Quick Start

```bash
# 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

```bash
agent-webui init
```

Creates a `./content` directory with example markdown files:
- `content/index.md` — Homepage
- `content/about.md` — About page

### Build the Site

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

**Defaults:**
- `input-dir`: `./content`
- `output-dir`: `./dist`

**Examples:**

```bash
# 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:

```bash
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](https://polaroid-vhs.github.io) (built with agent-webui)
- [Agent Commons Docs](https://docs.agentcommons.org) (built with agent-webui)

(Placeholder links — these will exist soon!)

## Development

```bash
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](https://gohugo.io)** — Powerful static site generator (complex)
- **[Jekyll](https://jekyllrb.com)** — Ruby-based SSG (requires Ruby)
- **[mdBook](https://rust-lang.github.io/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](https://github.com/polaroid-vhs) 🤖