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.

Every text value you pass to a py2html element method — Label, Button, Heading, Link, Frame, and so on — is automatically processed by escapeCharacters() before it is stored in the tag dictionary. This single method does two things at once: it HTML-escapes dangerous characters so your strings are safe to embed in a page, and it expands a set of lightweight bracket-based tokens into real HTML inline elements. You can write [*bold*] in a heading’s text argument and get <strong>bold</strong> in the output — no string concatenation or manual HTML required.

​
How escapeCharacters() Works

escapeCharacters(text) is a method on Parent. It is called internally by every element method that accepts a text value, so you rarely need to call it yourself. The processing happens in two passes:
  1. HTML-escape special characters — turns &, <, >, ", and ' into their safe HTML entity equivalents, and converts whitespace control characters into HTML equivalents.
  2. Expand markup tokens — replaces bracketed shorthand tokens with the corresponding HTML tags.
Because HTML-escaping runs before token expansion, tokens themselves are never accidentally escaped — the square brackets and their payload are matched on the original text, then replaced with literal HTML tag strings.

​
Special Character Escaping

Raw characterHTML output
&&amp;
<&lt;
>&gt;
"&quot;
'&#39;
\n<br>
\t&nbsp;&nbsp;&nbsp;&nbsp; (4 non-breaking spaces)

​
Markup Token Reference

The full set of supported tokens is listed below. Tokens follow the pattern [token content token] — an opening tag made of [ + keyword, the content, then the closing keyword + ].
Opening tokenClosing tokenHTML producedDescription
[**]<strong>…</strong>Bold text
[__]<em>…</em>Italic text
[``]<code>…</code>Inline code span
[``````]<pre><code>…</code></pre>Preformatted code block
[cc]<center>…</center>Centered text
[xxs xxs]<span style='font-size: 0.4rem;'>…</span>Extra-extra-small
[xs xs]<span style='font-size: 0.6rem;'>…</span>Extra-small
[s s]<span style='font-size: 0.8rem;'>…</span>Small
[m m]<span style='font-size: 1rem;'>…</span>Medium (base size)
[l l]<span style='font-size: 1.2rem;'>…</span>Large
[xl xl]<span style='font-size: 1.5rem;'>…</span>Extra-large
[xxl xxl]<span style='font-size: 2rem;'>…</span>Extra-extra-large
[xxxl xxxl]<span style='font-size: 3rem;'>…</span>Triple-extra-large
Font-size tokens require a trailing space on the opening token ([xl not [xl) and a leading space on the closing token ( xl] not xl]). This avoids false matches inside ordinary words.Bold, italic, code, and center tokens ([*, *], [_, _], [`, `], [c, c]) match purely on their bracket sequences — no surrounding spaces required.

​
Controlling Escaping with the escape Parameter

Two places in the API expose an escape flag that bypasses escapeCharacters() entirely:

​
TextNode(text, escape=True)

TextNode adds raw text to the tag list. Pass escape=False to inject pre-built HTML strings without double-escaping. 
page = Parent()

# Default: text is escaped and markup tokens are expanded
page.TextNode("[*Important:*] Read the [_fine print_].")

# escape=False: raw HTML is inserted verbatim
page.TextNode("<strong>Raw HTML</strong>", escape=False)

​
__call__(*args, escape=True, sep=" ")

Calling a Parent directly is shorthand for TextNode. The same escape keyword applies: 
page = Parent()
page("Hello [*world*]!")              # escape=True (default)
page("<hr>", escape=False)           # raw <hr> tag injected
page("Line 1", "Line 2", sep="\n")   # joined then escaped
Use escape=False only for trusted, pre-sanitised strings. Never pass unsanitised user input with escape=False — it creates an XSS risk.

​
Practical Examples

from py2html import Parent

page = Parent()

# Bold and italic inside a Label
page.Label(
    text="[*py2html*] makes HTML [_easy_].",
    fg="#1a1a2e",
    bg="#ffffff",
    padx=16,
    pady=10,
)

print(str(page))

​
Token Nesting and Ordering

escapeCharacters applies all replacements in a fixed sequence. Outer tokens are replaced independently of inner ones — tokens do not nest. For example, [*bold and [_italic_]*] will produce <strong>bold and <em>italic</em></strong> only because both patterns are replaced in the same pass; py2html does not validate bracket pairing.
Token replacement is purely textual (Python str.replace). There is no parser, so mismatched or overlapping tokens may produce malformed HTML. Keep each token on its own level and avoid nesting the same token type.

Build docs developers (and LLMs) love

Get started for freeTalk to us