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

pip install htmlforge

Development install:

pip install -e ".[dev]"

Quick Start

1. Write a Python page script mysite.py

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

# 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

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.

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:

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

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

Example: Multi-page Site

# 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...")

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

License

MPL-2.0