Metadata-Version: 2.5
Name: htmlforge
Version: 0.0.1
Summary: Build web pages with Python, export to HTML with a single command
Project-URL: Homepage, https://github.com/htmlforge/htmlforge
Author: htmlforge contributors
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: builder,html,page,static-site,web
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# htmlforge

Build web pages with Python, export to HTML with a single command — like manim generates videos.

```
manim   scene.py MyScene  →  mp4
htmlforge    page.py  MyPage   →  html
```

## Installation

```bash
pip install htmlforge
```

Development install:

```bash
pip install -e ".[dev]"
```

## Quick Start

### 1. Write a Python page script `mysite.py`

```python
from htmlforge import Doc

page = Doc("My Site")

# Generate styles with Python code (no CSS needed!)
page.style("body", background="#f5f5f5", font_family="sans-serif")
page.style(".py-card", border_radius="12px", box_shadow="0 2px 8px rgba(0,0,0,.1)")

# Build the page
page.heading("Welcome to My Site")
page.text("Built with **htmlforge**, supports *Markdown* syntax")

page.card("Features",
    "40+ HTML components",
    "Generate styles with Python code",
    "Export HTML with one command",
)

page.table(
    ["Feature", "Description"],
    [
        ["Components", "40+ HTML components"],
        ["Built-in theme", "Works out of the box"],
        ["CLI tools", "render / serve / watch"],
    ],
)

page.button("Click me", on_click="alert('Hello!')", color="#4CAF50")
```

### 2. Run the command to export HTML

```bash
# Basic render
htmlforge render mysite.py

# Specify output directory
htmlforge render mysite.py -o build

# Render and start a local server
htmlforge render mysite.py -s

# Watch for file changes and auto-rebuild
htmlforge render mysite.py -w

# Render a specific page (when file has multiple pages)
htmlforge render mysite.py MyPage
```

## CLI Commands

| Command | Description |
|---|---|
| `htmlforge render <file.py>` | Render all pages to `dist/` |
| `htmlforge render <file.py> -o <dir>` | Specify output directory |
| `htmlforge render <file.py> <page>` | Render only the specified page |
| `htmlforge render <file.py> -s` | Start HTTP server after render |
| `htmlforge render <file.py> -s -p 3000` | Specify server port |
| `htmlforge render <file.py> -w` | Watch for changes and auto-rebuild |

## Doc API — Ultra Simple

`Doc` is a high-level API designed for Python programmers who don't know HTML. It comes with a built-in theme — no CSS required to build great-looking pages.

```python
from htmlforge import Doc

page = Doc("Title")

# Generate styles with Python kwargs (no CSS strings!)
page.style("body", background="linear-gradient(135deg, #667eea, #764ba2)", color="white")
page.style("h1", font_size="3rem", text_align="center")
page.style(".py-card", background="rgba(255,255,255,.15)", backdrop_filter="blur(10px)")

# Content (supports **Markdown** syntax)
page.heading("Hello World")
page.text("Supports **bold**, *italic*, `code`, [links](url)")

page.card("Card Title", "Card content, **supports Markdown**")
page.list(["Item A", "Item B", "Item C"])
page.table(["Col 1", "Col 2"], [["a", "b"], ["c", "d"]])
page.button("Button", on_click="alert('hi')", color="#e74c3c")
page.input("Type here...", name="name")
page.select(["Option A", "Option B", "Option C"])
page.code("print('hello')", lang="python")
page.details("Collapsible", "Hidden content...")
page.nav(("Home", "/"), ("About", "/about"))
page.divider()

# Layout
page.row(Doc.make_card("A"), Doc.make_card("B"), Doc.make_card("C"))
```

## Page API — Fine-grained Control

Use `Page` + the component system when you need more control:

```python
from htmlforge import Page, H1, P, Div, Table, Button

page = Page("Title", lang="en")
page.add_css("body { font-family: sans-serif; }")
page.add(
    H1("Welcome"),
    P("Hello World"),
    Div(class_="card").add(
        H1("Features", level=2),
        P("Content..."),
    ),
)
```

### Element — Chainable API

```python
div = Div(id="main", class_="wrapper")
div.add(H1("Title"), P("Content"))          # Add child elements
div.css(color="red", font_size="16px")      # Set inline styles (camelCase → kebab-case)
div.attr("data-id", "123")                  # Set attributes
html = div.render()                          # → HTML string
```

### Components

| Category | Components |
|---|---|
| **Structure** | `Div`, `Section`, `Header`, `Footer`, `Nav`, `Main`, `Article`, `Aside`, `Span`, `Container` |
| **Text** | `H1`-`H6`, `P`, `Strong`, `Em`, `Blockquote`, `Code`, `Pre`, `Small`, `Mark` |
| **Links/Media** | `Link`, `Img`, `Video`, `Audio`, `Iframe`, `Canvas` |
| **Lists** | `Ul`, `Ol`, `Li`, `List` |
| **Tables** | `Table`, `Thead`, `Tbody`, `Tr`, `Th`, `Td`, `Caption` |
| **Forms** | `Form`, `Input`, `Textarea`, `Select`, `Option`, `Checkbox`, `Radio`, `Label`, `Button` |
| **Other** | `Hr`, `Br`, `Text`, `Progress`, `Details`, `Summary` |

## Example: Multi-page Site

```python
# site.py
from htmlforge import Doc

home = Doc("Home")
home.heading("Home")
home.text("Welcome to the home page")

about = Doc("About")
about.heading("About Us")
about.text("This is the about page")

blog = Doc("Blog")
blog.heading("Blog")
blog.text("Latest posts...")
```

```bash
htmlforge render site.py
# → dist/home.html, dist/about.html, dist/blog.html
```

## License

[MPL-2.0](LICENSE)
