Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nishad12323/py2html/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through building a complete HTML page from scratch using py2html. In fewer than 30 lines of Python you will create a heading, a paragraph, a button, a link, an image, and a container Frame — then render the whole thing to a formatted .html file.
Make sure py2html is installed and importable before continuing. See the Installation guide if you have not set it up yet.

​
Full example

The code below demonstrates every element covered in this quickstart. Read through it once, then follow the step-by-step breakdown underneath. 
import sys
from pathlib import Path

# Adjust this if py2html lives somewhere other than ~/py2html/
sys.path.insert(0, str(Path.home()))

import py2html

# 1. Create the root Parent object
page = py2html.Parent()

# 2. Add a top-level heading
page.Heading(
    level=1,
    text="Welcome to py2html",
    fg="#1a1a2e",
    padx=20,
    pady=20,
)

# 3. Add a descriptive paragraph (Label)
page.Label(
    text="Build [* complete *] HTML pages using nothing but Python.",
    fg="#333333",
    bg="#f9f9f9",
    padx=20,
    pady=10,
)

# 4. Add a call-to-action button
page.Button(
    text="Get Started",
    fg="#ffffff",
    bg="#00a651",
    bdradius="8px",
    padx=20,
    pady=10,
)

# 5. Add a hyperlink
page.Link(
    href="https://github.com/nishad12323/py2html",
    text="View the source on GitHub",
    fg="#0070f3",
    padx=20,
    pady=5,
    text_decor="underline",
)

# 6. Add an image
page.Image(
    src="https://via.placeholder.com/400x200",
    alt="A placeholder image",
    width="400px",
    height="200px",
    bdradius="8px",
)

# 7. Build a Frame that groups two child elements side by side
card_content = py2html.Parent()
card_content.Label(
    text="[xl Card Title xl]",
    fg="#1a1a2e",
    bg="transparent",
    padx=10,
    pady=4,
)
card_content.Label(
    text="This label lives inside a flex Frame.",
    fg="#555555",
    bg="transparent",
    padx=10,
    pady=4,
)

page.Frame(
    content=card_content,
    bg="#eef6ff",
    bdradius="12px",
    padx=16,
    pady=16,
    content_manager="flex",
    flex_config={
        "flex-direction": "column",
        "align-items": "flex-start",
        "justify-content": "flex-start",
        "flex-wrap": "nowrap",
        "gap": "8px",
    },
)

# 8. Render and save
html_output = page.getHTML(format=True)
print(html_output)
page.saveToFile("index.html")
print("Saved to index.html")

​
Step-by-step breakdown

1

Create the Parent object

Every py2html page starts with a Parent. It maintains an ordered list of all elements you add and is responsible for rendering the final HTML.
import py2html

page = py2html.Parent()
At this point page holds an empty element list. The root <html>, <head>, and <body> tags are added automatically when you call getHTML().You can also configure the Parent with config() after construction:
page.config(title="My Page", style="body { font-family: sans-serif; }")
config() accepts title (sets the document title string) and style (must be a string).
2

Add a Heading

Heading renders an <h1> through <h6> tag. The level parameter controls which heading rank is used (default 1).
page.Heading(
    level=1,
    text="Welcome to py2html",
    fg="#1a1a2e",
    padx=20,
    pady=20,
)
Default values: level=1, text="Py2HTML Heading", fg="#333", bg="transparent", bd="none", bdradius="0px", padx=0, pady=0.
Text passed to any element method is automatically HTML-escaped. You do not need to sanitise user-supplied strings before passing them in.
The method appends the heading to page.tags and returns the integer index of the new element — useful if you want to reference it later with page[index].
3

Add a Label and a Button

Label renders a <p> tag. Button renders a <button> tag. Both accept the same colour and padding parameters.
# Inline markup: [* … *] wraps text in <strong>
page.Label(
    text="Build [* complete *] HTML pages using nothing but Python.",
    fg="#333333",
    bg="#f9f9f9",
    padx=20,
    pady=10,
)

page.Button(
    text="Get Started",
    fg="#ffffff",
    bg="#00a651",
    bdradius="8px",
    padx=20,
    pady=10,
)
Default values for Button: fg="#00a651", bg="#deffee", bd="none", bdradius="50px", text="Py2HTML", padx=15, pady=15.Default values for Label: fg="#000", bg="#fff", bd="none", bdradius="50px", text="Py2HTML", padx=15, pady=15.Notice the [* … *] syntax inside the Label text. py2html’s inline markup processor converts this to <strong>…</strong> automatically.py2html also provides Text for multiline text input (<textarea>), with the same parameter set as Label.
4

Add a Link and an Image

Link renders an <a> tag. The href parameter is kept raw (not HTML-escaped as content) so that valid URLs are preserved correctly.Image renders a self-closing <img /> tag. Supply width and height as CSS strings such as "400px" or "50%".
page.Link(
    href="https://github.com/nishad12323/py2html",
    text="View the source on GitHub",
    fg="#0070f3",
    padx=20,
    pady=5,
    text_decor="underline",
)

page.Image(
    src="https://via.placeholder.com/400x200",
    alt="A placeholder image",
    width="400px",
    height="200px",
    bdradius="8px",
)
Default values for Link: href="https://example.com", text="Click Here", fg="#00a651", bg="transparent", bd="none", bdradius="0px", padx=0, pady=0, text_decor="underline".Default values for Image: src="", alt="", width=None, height=None, bd="none", bdradius="0px".
5

Group elements in a Frame

Frame renders a <div>. To place multiple elements inside it, first create a child Parent, add elements to that, then pass it as the content argument.
card_content = py2html.Parent()
card_content.Label(text="[xl Card Title xl]", fg="#1a1a2e", bg="transparent", padx=10, pady=4)
card_content.Label(text="This label lives inside a flex Frame.", fg="#555555", bg="transparent", padx=10, pady=4)

page.Frame(
    content=card_content,
    bg="#eef6ff",
    bdradius="12px",
    padx=16,
    pady=16,
    content_manager="flex",
    flex_config={
        "flex-direction": "column",
        "align-items": "flex-start",
        "justify-content": "flex-start",
        "flex-wrap": "nowrap",
        "gap": "8px",
    },
)
Setting content_manager="flex" enables flexbox on the container. The flex_config dictionary maps directly to CSS flex properties. The content_manager parameter (default "block") controls the CSS display property of the <div>.Full Frame signature: Frame(fg="#000", bg="#fff", bd="none", bdradius="50px", content="Py2HTML", padx=15, pady=15, width="auto", height="auto", marginx=0, marginy=0, content_manager="block", flex_config={...}, position="static", offset={...}).
6

Render to HTML and save to file

Call getHTML(format=True) to produce a complete, prettified HTML string. Use saveToFile() to write it to disk in one call, or save() to write prettified HTML to an already-open file object.
# Print the formatted HTML to stdout
html_output = page.getHTML(format=True)
print(html_output)

# Write unformatted HTML to a named file
page.saveToFile("index.html")

# Write prettified HTML to an open file object
with open("index_pretty.html", "w") as f:
    page.save(f)
saveToFile(filename) opens the file in write mode and calls getHTML() internally (without format=True), so the saved HTML is compact. save(destination) calls getHTML(format=True) and writes the prettified result to the file object you provide.str(page) (or page.__str__()) is equivalent to page.getHTML(format=True) and returns a prettified HTML string directly.

​
Tag indexing and deletion

Every element method returns the integer index of the newly added tag in page.tags. You can use page[index] to retrieve the raw tag dictionary, or del page[index] to remove it. 
page = py2html.Parent()
idx = page.Heading(text="My Heading")   # returns 0
page.Label(text="My Label")             # returns 1

print(page[0])      # {'type': 'h1', 'fg': '#333', ...}
del page[1]         # removes the Label

​
Calling the Parent directly

Calling a Parent instance like a function adds a TextNode from one or more string arguments: 
page = py2html.Parent()
page("Hello,", "world!")           # adds a text node "Hello, world!" (escaped)
page("Raw <br>", escape=False)     # adds unescaped HTML text
The sep keyword argument (default " ") controls the separator used when joining multiple positional arguments.

​
Expected HTML output (abbreviated)

Running the example produces a document similar to the following. The exact whitespace depends on BeautifulSoup.prettify(). 
<html>
 <head>
  <title>
   Py2HTML Site
  </title>
 </head>
 <body style="padding: 0; margin: 0;">
  <h1 style="color: #1a1a2e; background: transparent; border: none; border-radius: 0px; padding: 20px 20px;">
   Welcome to py2html
  </h1>
  <p style="color: #333333; background: #f9f9f9; border: none; border-radius: 50px; padding: 10px 20px;">
   Build <strong>complete</strong> HTML pages using nothing but Python.
  </p>
  <button style="color: #ffffff; background: #00a651; border: none; border-radius: 8px; padding: 10px 20px;">
   Get Started
  </button>
  <a href="https://github.com/nishad12323/py2html"
     style="color: #0070f3; background: transparent; border: none; border-radius: 0px;
            padding: 5px 20px; text-decoration: underline;">
   View the source on GitHub
  </a>
  <img style="border: none; border-radius: 8px; width: 400px; height: 200px;"
       src="https://via.placeholder.com/400x200"
       alt="A placeholder image"/>
  <div style="color: #000; background: #eef6ff; border: none; border-radius: 12px;
              padding: 16px 16px; width: auto; height: auto; margin: 0 0;
              display: flex; align-items: flex-start; justify-content: flex-start;
              flex-direction: column; flex-wrap: nowrap; gap: 8px; position: static; …">
   <p style="…">
    <span style="font-size: 1.5rem;">Card Title</span>
   </p>
   <p style="…">
    This label lives inside a flex Frame.
   </p>
  </div>
 </body>
</html>

​
Next steps

Now that you have a working page, explore the rest of the element API:
  • Add inline JavaScript with page.Script(code="alert('hello!')")
  • Insert raw HTML with page.TextNode(text="<hr>", escape=False)
  • Use any HTML tag name with page.CustomTag(tag_name="article", content="…")
  • Build multi-section layouts by nesting Frame containers inside each other

Build docs developers (and LLMs) love

Get started for freeTalk to us