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
htmlforge   script   app.py        →  js

Installation

pip install htmlforge

Quick Start

1. Write a Python page script mysite.py

from htmlforge import Doc

page = Doc("My Site")

# Generate styles with Python kwargs (no CSS strings!)
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 / script"],
    ],
)

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

JavaScript & DOM Interaction

Bind events to elements

from htmlforge import Button

btn = Button("Click me")

# Bind raw JavaScript
btn.on("click", "alert('hello')")
btn.on("mouseover", "this.style.color='red'")

# Bind Python code (auto-converted to JS)
btn.on_py("click", "print('clicked!')")
# → onclick="console.log('clicked!');"

Add JavaScript to the page

# Raw JavaScript
page.js("document.title = 'Dynamic'")
page.js("function greet() { alert('hello'); }")

# External JS file
page.js_file("app.js")

# Python code → JavaScript (auto-converted)
page.py_script('''
def greet(name):
    print(f"Hello {name}")
greet("World")
''')

# Run on page load (DOMContentLoaded)
page.on_ready("console.log('Page loaded!')")
page.on_ready_py('print("Ready!")')

DOM manipulation helpers

# Get element properties (returns JS expressions)
val   = page.get_attr("#input", "value")   # → document.querySelector('#input').getAttribute('value')
text  = page.get_text("#title")            # → document.querySelector('#title').textContent
html  = page.get_html("#content")          # → document.querySelector('#content').innerHTML
value = page.get_value("#myInput")         # → document.querySelector('#myInput').value

# Set element properties (generates JS scripts)
page.set_attr("#el", "class", "active")
page.set_text("#title", "New Title")
page.set_html("#content", "<b>bold</b>")
page.set_value("#input", "hello")

# Visibility
page.show("#modal")
page.hide("#loading")
page.toggle("#sidebar")

# CSS class manipulation
page.add_class("#el", "active")
page.remove_class("#el", "hidden")
page.toggle_class("#menu", "open")

Python → JavaScript Transpiler

Use htmlforge script to convert Python files to JavaScript:

htmlforge script app.py            # → app.js
htmlforge script app.py -o out.js  # → out.js
htmlforge script app.py --helpers  # include DOM helpers ($, $$, getAttr, setAttr, ...)

Or use it programmatically:

from htmlforge import py_to_js, convert_file

# Convert Python source string to JS
js = py_to_js("""
def greet(name):
    print(f"Hello {name}")

for i in range(10):
    greet("World")
""")

# Convert a file
convert_file("app.py", "app.js")

Supported Python → JS conversions

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
div.on("click", "alert('clicked')")         # Bind JS event
div.on_py("click", "print('clicked')")      # Bind Python event (auto-converted)
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