# django-div

> Build and parse HTML in Python with Pydantic models.


---

<!-- index -->

# django-div

Build and parse HTML in Python with Pydantic models.

```python
from django_div import A, Div, P

print(Div(P("Hello, World!"), A("Click", href="/x"), class_="card"))
```

```html
<div class="card"><p>Hello, World!</p><a href="/x">Click</a></div>
```

Children are positional, attributes are keyword arguments. Text is escaped,
void elements self-close, and Python attribute spellings map onto HTML ones.

## Why this exists

Most HTML-in-Python libraries build markup and stop there. Here the tree is a
Pydantic model, which means the same objects can go in four directions:

- **Build**  Compose elements as Python values, with escaping handled for you.  [ Building HTML](building/)
- **Parse**  Read existing markup back into the same tree, then search and edit it.  [ Parsing HTML](parsing/)
- **Serialize**  Round-trip a page through JSON with its element classes intact.  [ Serializing](serializing/)
- **Render in Django**  Components as templates, with escaping that works both ways.  [ Django](django/)

## Install

With uv, create a virtual environment if needed and install the package:

```console
uv venv
uv pip install django-div
```

With pip, install into your active virtual environment:

```console
python -m pip install django-div
```

For uv-managed projects, `uv add` records the dependency in `pyproject.toml`.
The same extras below also work with `uv pip install` and `python -m pip install`:

```console
uv add django-div            # building only
uv add 'django-div[parse]'   # plus from_html()/parse(), via bs4 + lxml
uv add 'django-div[html5]'   # spec-exact parsing, ~3x slower than lxml
uv add 'django-div[markdown]' # plus from_markdown(), via markdown-it-py
```

django-div needs Python 3.12 or later.
Pydantic is the only hard dependency. Parsers are optional and their imports
are guarded, so building HTML pulls in nothing else. Django is optional too:
only `django_div.django` imports it.

## A tour in one page

```python
from django_div import Div, H1, Li, P, Span, Ul, from_html

# Nesting, attributes, escaping
Div(H1("Title"), P("a < b"), class_="page")
# <div class="page"><h1>Title</h1><p>a &lt; b</p></div>

# None and False children drop out, so inline conditionals work
Div("Hello", user and Span(user.name))

# Collections flatten, so comprehensions splat in
Ul(Li(item) for item in items)

# Parse markup into the same kind of tree
page = from_html('<div><a href="/x" target="_blank">Click</a></div>')
page.find("a").attrs["href"]        # '/x'
page.text                           # 'Click'

# Edit it and render it back out
for link in page.find_all("a", target="_blank"):
    link.attrs["rel"] = "noopener"
print(page)
```

## Where to next

The four cards above cover building, parsing, serializing, and Django. Beyond
those:

- [Markdown](markdown/): render the tree as Markdown, read Markdown in
- Cookbooks: [HTML](cookbook/) · [Django](django-cookbook/) ·
  [Markdown](markdown-cookbook/)
- [API reference](reference/): every function, class, and constant
- [Contributing](contributing/): setup, conventions, tests

## Reusable elements and browser data

Derive element variants with `with_attrs()`, render explicit ARIA states
from Python booleans, and pass browser data with `JsonScript`.
The [cookbook](cookbook/) includes button variants, disclosures,
HTML templates, and JSON data recipes.

Search by class tokens or custom conditions with predicates, and use
`transform()` to replace, remove, or unwrap nodes on a copied tree.
See [searching](parsing/#searching) and
[transforming a copy](parsing/#transforming-a-copy) for traversal and
copy semantics.

## llms.txt

This documentation is available in the [llms.txt](https://llmstxt.org/)
format, a Markdown convention suited to LLMs and AI coding assistants.

Two files are published:

- [`llms.txt`](https://django-div.readthedocs.io/en/latest/llms.txt): a short
  description of the project plus links to each section. The structure is
  described [here](https://llmstxt.org/#format).
- [`llms-full.txt`](https://django-div.readthedocs.io/en/latest/llms-full.txt):
  the same index with the content of every page inlined.

Every page is also published as Markdown alongside its HTML, so you can point
an assistant at a single section rather than the whole corpus. Append `.md` to
the page name:

```text
https://django-div.readthedocs.io/en/latest/building.md
https://django-div.readthedocs.io/en/latest/django.md
```

## Where it came from

django-div started as five throwaway scripts trying to answer one question:
how do you make `Div("hello", class_="x")` work when Pydantic wants keyword
fields? Those experiments are still in the git history at the
`Baseline: original django-div demo experiments` commit.

## Prior art

[htpy](https://htpy.dev), [dominate](https://github.com/Knio/dominate), and
[django-components](https://github.com/django-components/django-components)
cover adjacent ground, and htpy in particular landed on a very similar
constructor shape. django-div's angle is the Pydantic model underneath: the
same objects parse, validate, and serialize.


---

<!-- building -->

# Building HTML

Every HTML element has a class, named after the tag with a capital letter:
`Div`, `P`, `H1`, `Textarea`. The set covers all 138 elements MDN tracks --
the 113 current ones in the
[WHATWG living standard](https://html.spec.whatwg.org/multipage/indices.html#elements-3)
plus 19 deprecated and 6 experimental, which warn when you build one --
each documented on [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element).
Children are positional arguments, attributes are keyword arguments.

```python
from django_div import A, Div, H1, P

Div(
    H1("Welcome"),
    P("A paragraph with ", A("a link", href="/docs"), "."),
    class_="page",
)
```

```html
<div class="page"><h1>Welcome</h1><p>A paragraph with <a href="/docs">a link</a>.</p></div>
```

Rendering happens on `str()`, so `print(tag)`, f-strings, and
`"".join(...)` all work directly.

## Attributes

Python spellings are translated to HTML ones: a trailing underscore is
dropped, and remaining underscores become hyphens.

| Python | HTML |
| --- | --- |
| `class_="card"` | `class="card"` |
| `for_="email"` | `for="email"` |
| `data_test_id="hero"` | `data-test-id="hero"` |
| `aria_label="Close"` | `aria-label="Close"` |
| `hx_get="/rows"` | `hx-get="/rows"` |
| `http_equiv="refresh"` | `http-equiv="refresh"` |

### Reserved words

The trailing underscore also covers every Python keyword. Add one underscore
to the end of the keyword, and the rule removes it again on render.

| Python | HTML | Where it applies |
| --- | --- | --- |
| `class_` | `class` | every element |
| `for_` | `for` | `<label>`, `<output>` |
| `as_` | `as` | `<link>` |
| `async_` | `async` | `<script>` |
| `is_` | `is` | custom elements |
| `in_` | `in` | SVG filters |
| `from_` | `from` | SVG `<animate>` |

Soft keywords need no underscore. Python accepts `type`, `match`, and `case`
as argument names, so write `Input(type="checkbox")` directly.

An attribute name that is not a Python identifier cannot be a keyword
argument. Pass a dictionary instead, and the name goes through unchanged:

```python
Div(**{"hx-on:click": "alert(1)", "@click": "open = true"})
```

There is no exception table. The rule above derives every attribute name on
its own, and the seven rows above are the complete list: `tests/test_attributes.py`
checks them against every attribute name MDN tracks, for HTML and SVG both.

### Boolean attributes

For attributes other than `aria-*`, `True` renders the attribute bare.
`False` and `None` drop it entirely, which
means you can pass a flag straight through.

```python
Input(type="checkbox", checked=is_selected, disabled=False)
```

```html
<input type="checkbox" checked />
```

ARIA attributes use explicit string values: `aria_expanded=False` renders
`aria-expanded="false"`, and `aria_pressed=True` renders
`aria-pressed="true"`. `None` still omits the attribute. This applies to
both Python spellings and literal `aria-*` keys.

### `class` and `style` take structures

`class` accepts a string, any iterable, or a mapping of name to condition:

```python
Div(class_="btn")                            # class="btn"
Div(class_=["btn", "btn-primary"])           # class="btn btn-primary"
Div(class_={"btn": True, "is-active": False})  # class="btn"
```

`style` accepts a string or a mapping, with property names normalized the
same way as attributes:

```python
Div(style={"color": "red", "font_size": "2rem"})
```

```html
<div style="color: red; font-size: 2rem"></div>
```

## Children

Anything that isn't already an element is converted to escaped text.

```python
P("a < b")        # <p>a &lt; b</p>
P(42)             # <p>42</p>
```

### Conditionals

`None` and `False` children are dropped, so `and`/`or` expressions work
inline without a temporary variable.

```python
Div(
    H1(title),
    user and P(f"Signed in as {user.name}"),
    error or None,
)
```

### Collections flatten

Lists, tuples, sets, ranges, and any iterator are flattened, so
comprehensions and generators splat in without unpacking.

```python
Ul(Li(item) for item in items)
Div([Span("a"), Span("b")])
```

Why a whitelist and not `Iterable`

Strings are iterable, and so are Django's lazy translation proxies.
Flattening everything iterable would turn `Div(gettext_lazy("Hi"))` into
one text node per character. `is_collection()` names the types that
actually mean "a group of children".

### Building in stages

Calling a tag returns a **copy** with the extra children appended, leaving
the original untouched. That makes a configured element reusable as a
prototype.

```python
card = Div(class_="card")

card(H1("First"))     # <div class="card"><h1>First</h1></div>
card(H1("Second"))    # <div class="card"><h1>Second</h1></div>
card                  # <div class="card"></div>
```

Use `with_attrs()` to derive a variant with replacement attributes:

```python
base = Button("Save", class_="btn", title="Save changes")
primary = base.with_attrs(class_="btn primary", disabled=True, title=None)
# <button class="btn primary" disabled>Save</button>
```

The original stays unchanged. Names normalize just as in constructors
(`class_` → `class`, `data_id` → `data-id`). Supplied values replace existing
ones, including the entire class value; unspecified attributes remain.
`None` omits an attribute when rendered. `False` follows the normal boolean
rules, so `aria_expanded=False` still renders `aria-expanded="false"`.

The copy keeps its subclass and has an independent attribute dictionary and
child list. Existing child objects and nested attribute values are shared,
matching the shallow-copy behavior of calling a tag.

## Escaping

Text children and attribute values are escaped. This is not opt-in, so
untrusted content is safe by default.

```python
Div("<script>alert(1)</script>")
# <div>&lt;script&gt;alert(1)&lt;/script&gt;</div>

Div(title='he said "hi"')
# <div title="he said &quot;hi&quot;"></div>
```

To emit markup you have already vetted, wrap it in `Raw`:

```python
from django_div import Raw

Div(Raw(content="<b>bold</b>"))   # <div><b>bold</b></div>
```

Raw is a loaded gun

`Raw` bypasses escaping completely. Never build one from user input.

Anything implementing the `__html__` protocol (a Django `SafeString`, a
`markupsafe.Markup`, a rendered form) is trusted and passes through
unescaped, so interop with other libraries needs no special handling.

### Comments

`Comment` renders an HTML comment. A comment is not an escaping context, so
its content is not HTML-escaped. Instead the three comment-syntax rules are
neutralized on render, because each one would otherwise let content escape
the comment:

```python
Comment(content="note")    # <!--note-->
Comment(content="a--b")    # <!--a- -b-->
Comment(content=">boom")   # <!-- >boom-->
Comment(content="x-")      # <!--x- -->
```

- `--` inside a comment would end it early, so it becomes `- -`.
- HTML5 reads `<!-->` and `<!--->` as *complete* comments, so a leading `>`
  or `->` would leave the rest of the content parsing as live markup. For
  untrusted content, that is script execution. A space is padded in front.
- A trailing `-` would produce the invalid `<!--x--->`; a space is padded.

The padding is the whole defense: unlike a `<script>` break-out, a space
changes nothing about what a comment means, so there is no reason to raise.
Content that hits a rule comes back slightly altered on a round trip;
ordinary comments are untouched.

## Element categories

Three groups of elements behave differently, and django-div enforces the
difference rather than leaving it to you.

### Void elements

`br`, `img`, `input`, `hr`, and friends self-close and cannot have children.
Passing children raises instead of silently dropping them.

```python
Br()                          # <br />
Img(src="a.png", alt="A cat") # <img src="../a.png" alt="A cat" />

Br("text")
# ValueError: <br> is a void element and cannot have children
```

### Raw text elements

`script` and `style` hold code, not text, so their content is **not**
escaped. Escaping it would change what the code means: `if (a < b)` is not
`if (a &lt; b)`.

```python
Script("if (a < b) { go() }")   # <script>if (a < b) { go() }</script>
Style("a > b { color: red }")   # <style>a > b { color: red }</style>
```

Because nothing escapes a raw text element except its own closing tag,
content containing that closing tag would break out of the element, and for
a `<script>`, the rest would run as markup. django-div refuses rather than
mangling it:

```python
str(Script("</script><script>alert(1)</script>"))
# ValueError: <script> content cannot contain '</script'; it would end the element
```

Interpolating into a script

Never build a `Script` from untrusted input. The closing-tag check stops
the most obvious break-out, not every JavaScript injection. To pass data
to the browser, render it as JSON into a `data-` attribute or a
`<script type="application/json">` block instead.

### Preformatted elements

`pre` and `textarea` have significant whitespace. This only affects parsing (see
[Parsing HTML](../parsing/)), since building preserves exactly what you
pass.

## Elements not in the list

`Tag` takes the name as its first argument, and handles anything, including
custom elements and web components:

```python
from django_div import Tag

Tag("my-widget", "hi", data_state="ready")
# <my-widget data-state="ready">hi</my-widget>
```

To get a reusable class instead, use `tag_class()`. It registers the result,
so parsing will produce that class too:

```python
from django_div import tag_class

MyWidget = tag_class("my-widget")
MyWidget("hi", data_state="ready")
```


---

<!-- parsing -->

# Parsing HTML

`from_html()` turns markup back into the same tree the constructors build, so
a parsed page can be searched, edited, re-rendered, or serialized.

```console
uv add 'django-div[parse]'
```

```python
from django_div import from_html

page = from_html('<div class="card"><a href="/x">Click</a></div>')

type(page)                      # <class 'django_div.Div'>
page.find("a").attrs["href"]    # '/x'
page.text                       # 'Click'
```

## `parse()` and `from_html()`

`parse()` always returns a list of top-level items. `from_html()` unwraps the
single-root case, which is what you usually want.

```python
from django_div import parse

parse("<p>a</p><p>b</p>")       # [P(...), P(...)]
from_html("<p>a</p><p>b</p>")   # [P(...), P(...)]
from_html("<p>a</p>")           # P(...)
```

## Searching

```python
page.text                          # all text in the subtree, unescaped
page.find("a")                     # first matching descendant, or None
page.find("a", class_="external")  # match on attributes too
page.find_all("a")                 # every matching descendant
page.iter_find("a")                # the same, lazily
page.walk()                        # every node, depth first, including text
```

Attribute names use the same Python spellings as the constructors, so
`class_="external"` matches `class="external"`.

```python
for heading in page.find_all("h2"):
    print(heading.text)
```

Pass a predicate as the first argument for class tokens or other conditions:

```python
page.find(lambda node: node.has_class("card"))
page.find_all(lambda node: node.tag in {"h2", "h3"})
page.iter_find(lambda node: node.has_class("external"), target="_blank")
```

All three search methods visit descendant tags in depth-first document order,
excluding the root. They traverse fragments but never pass fragments or text
nodes to predicates. Keyword attributes still match by exact equality and
filter candidates before the predicate runs. `find()` stops at the first
match. Predicates should inspect nodes without modifying the tree.

## Editing

Parsed trees are ordinary models. Mutate `attrs`, append to `children`, then
render.

```python
page = from_html(response.text)

for link in page.find_all("a", target="_blank"):
    link.attrs["rel"] = "noopener"

print(page)
```

### Transforming a copy

`transform(visitor)` copies the tree and visits every node, including text,
comments, fragments, and the root. Children are visited in document order
before their parent, so parents receive their already-transformed children.

```python
from django_div import Tag


def remove_scripts(node):
    if isinstance(node, Tag) and node.tag == "script":
        return None
    return node


cleaned = page.transform(remove_scripts)
```

Return the node to keep it, another `HtmlItem` to replace it, or `None` to
remove it with its subtree. Return `Fragment(node.children)` to unwrap an
element, or a fragment of new elements to replace one node with siblings.
Returned replacements are not traversed again. Descendants of a removed
parent have already been visited. Removing the root returns `None`.

Callbacks receive copies, with independent child lists and attribute
dictionaries and preserved subclasses. Nested attribute values remain
shared, so replace a style/class mapping instead of editing it in place.
A node appearing twice in the source is copied separately for each occurrence.
A replacement supplied by the callback is used as-is; returning an external
node shares that object. Exceptions propagate without changing the source
unless the callback itself mutates shared or external objects.

Traversal is iterative and supports deep trees. The callback must return an
`HtmlItem` or `None`; wrap text in `Text` and siblings in `Fragment`.
This is structural editing, not HTML sanitization. See the
[tree filtering recipe](../cookbook/#keep-only-certain-elements).

## Choosing a parser

Parsing goes through BeautifulSoup, which is a front end over several
backends. django-div picks the best one installed (`lxml`, then `html5lib`,
then the standard library), because they are not equivalent:

| Input | `html.parser` | `lxml` | `html5lib` |
| --- | --- | --- | --- |
| `<p>one<p>two` | `<p>one<p>two</p></p>` | `<p>one</p><p>two</p>` | `<p>one</p><p>two</p>` |
| `<ul><li>a<li>b</ul>` | nested `<li>` | correct | correct |
| 46 KB document | 28.8 ms | **17.8 ms** | 54.2 ms |

The standard library parser nests implicit closes instead of closing them,
which quietly produces a wrong tree, and it isn't the fastest either. It
remains the fallback because it needs no install.

Override per call when you need to:

```python
from_html(markup, parser="html5lib")
```

`best_parser()` reports what would be chosen.

## Fragments stay fragments

lxml and html5lib wrap a fragment in an invented `<html><body>` skeleton.
That would turn a parse-edit-render round trip into a rewrite, so django-div
strips wrappers the source did not ask for.

```python
from_html("<p>hi</p>")    # P(...), not Html(Body(P(...)))
```

If the source really does contain `<html>`, `<head>`, or `<body>`, those are
kept.

## Whitespace

Whitespace between two elements is a word break in the rendered page, so it
is preserved, but collapsed to a single space, since the source indentation
itself carries no meaning.

```python
from_html("<p><b>a</b> <b>b</b></p>")
# <p><b>a</b> <b>b</b></p>          the space matters

from_html("<div>\n    <p>one</p>\n    <p>two</p>\n</div>")
# <div><p>one</p> <p>two</p></div>  indentation collapsed
```

Inside `pre` and `textarea`, whitespace is significant and kept verbatim.

## Comments and doctypes

Comments survive as `Comment` items and doctypes as `Doctype` items, so a
whole document round-trips:

```python
parse("<!DOCTYPE html><!--note--><p>hi</p>")
# [Doctype(...), Comment(...), P(...)]
```

`Doctype.content` is what follows `<!DOCTYPE`: `"html"` for modern
documents, or the full legacy identifier string when parsing old markup.

## Limits

Parsing is a tree conversion, not a browser. A few things to expect:

- Character references are resolved by the parser, so `&amp;` comes back as
  `&` and is re-escaped on render. The output is equivalent, not identical.
- Attribute order follows the source, but duplicate attributes are collapsed
  by the parser before django-div sees them.
- Malformed markup is repaired according to whichever backend is in use, so
  round-tripping broken HTML gives you the repaired version.
- Attribute names come back lowercased, because that is what an HTML parser
  does. This matters for inline SVG and MathML only, where names are
  case-sensitive:

```python
from_html('<svg viewBox="0 0 24 24"></svg>').attrs
# {'viewbox': '0 0 24 24'}   a browser ignores this spelling
```

Building SVG keeps the case. Reading it back does not, so repair the names
  yourself if you must round-trip inline SVG.

## Class tokens and readable text

Search attributes use exact equality. To find elements carrying a class
among several tokens, pass a predicate to the lazy iterator:

```python
links = page.iter_find(lambda node: node.tag == "a" and node.has_class("external"))
page.get_text(" ", strip=True)  # trim text nodes and join with spaces
```

`link.classes` gives the token list for string, iterable, or mapping class
values. `has_class()` reflects edits to `attrs["class"]` immediately.

## Working with multiple roots

Use a `Fragment` when you want multiple roots to act as one renderable tree:

```python
from django_div import Fragment, parse

content = Fragment(parse("<h1>Title</h1><p>Body</p>"))
content.find("p").text          # 'Body'
content.get_text(" ", strip=True)  # 'Title Body'
str(content)                   # '<h1>Title</h1><p>Body</p>'
```

Wrapping does not change the parser's handling of whitespace or its return
types. Fragment boundaries are Python tree structure and have no HTML marker,
so parsing rendered HTML does not restore those boundaries; JSON does.


---

<!-- serializing -->

# Serializing

Every item is a Pydantic model, so a tree dumps to a dict or JSON and loads
back with its element classes intact.

```python
from django_div import Div, P, Tag

tree = Div(P("hi"), class_="card")
payload = tree.model_dump_json()

restored = Tag.model_validate_json(payload)
str(restored) == str(tree)          # True
type(restored.children[0])          # <class 'django_div.P'>
```

## The shape

```python
Div(P("x"), class_="card").model_dump()
```

```python
{
    "type": "tag",
    "tag": "div",
    "attrs": {"class": "card"},
    "children": [
        {
            "type": "tag",
            "tag": "p",
            "attrs": {},
            "children": [{"type": "text", "content": "x"}],
        },
    ],
}
```

Two fields carry the type information:

`type`
:   Distinguishes the leaf kinds, which otherwise look identical: `Text`,
`Raw`, and `Comment` all hold a single `content` string.

`tag`
:   Names the element, so `Div` comes back as `Div` rather than a generic
`Tag`.

Attribute keys are stored in their **HTML** spelling, normalized when the
element is built. A hand-built tree and a parsed one are therefore
structurally identical.

```python
Div(class_="card").attrs == {"class": "card"}
```

## Loading

`Tag.model_validate()` and `Tag.model_validate_json()` dispatch on `tag`, so
you can load a tree without knowing what its root is.

```python
Tag.model_validate(payload)         # Div, P, whatever the root was
Div.model_validate(payload)         # forces Div, no dispatch
```

Unknown tags fall back to the generic `Tag`, which still renders correctly.
Registering the element first, with `tag_class()`, gets you the class back
instead.

## What this is good for

Serialization is the reason the models are Pydantic rather than plain
classes. It buys a few things that string-building alone doesn't:

- **Caching a rendered tree** as JSON, then reloading and patching part of it
  without re-parsing HTML.
- **Sending markup across a boundary** (a queue, an API) as structured data
  that can be validated on arrival rather than trusted as a string.
- **Diffing two versions of a page** structurally instead of textually.
- **Storing user-authored content** in a form you can inspect and constrain,
  rather than sanitizing HTML strings after the fact.

## Combining with parsing

Parsing and serializing compose, which is the whole point:

```python
from django_div import Tag, from_html

tree = from_html(response.text)     # HTML  -> models
payload = tree.model_dump_json()    # models -> JSON
tree = Tag.model_validate_json(payload)   # JSON -> models
print(tree)                         # models -> HTML
```


---

<!-- markdown -->

# Markdown

The tree renders to Markdown as well as HTML, and Markdown reads back into
the same kind of tree. Every example on this page is executed by
`tests/test_markdown.py`.

```python
from django_div import Div, H1, P, from_html
from django_div.markdown import from_markdown, to_markdown

to_markdown(Div(H1("Title"), P("Body text.")))   # '# Title\n\nBody text.'
from_markdown("# Title")                         # H1(...)
```

`to_markdown()` needs nothing extra; `from_markdown()` needs the `markdown`
extra:

```console
uv add 'django-div[markdown]'
```

## Writing Markdown

`to_markdown()` takes one item, a list of items (what `parse()` and
`from_markdown()` return), or anything in between:

```python
to_markdown(H1("Title"))                    # '# Title'
to_markdown(Div(H1("Title"), P("Body")))    # blocks joined by blank lines
to_markdown([H1("A"), P("b")])              # '# A\n\nb'
```

Because parsing produces the same tree, `from_html` composes with it into an
HTML-to-Markdown converter:

```python
to_markdown(from_html("<article><h1>Title</h1><p>Body with <a href='/x'>a link</a>.</p></article>"))
# '# Title\n\nBody with [a link](/x).'
```

### What maps to what

| HTML | Markdown |
| --- | --- |
| `h1`–`h6` | `#` … `######` |
| `p` | paragraph |
| `em` / `i`, `strong` / `b` | `*x*`, `**x**` |
| `s` / `del` | `~~x~~` |
| `code`, `pre` | `` `x` ``, fenced block (language from `class="language-*"`) |
| `a`, `img` | `[text](href)`, `![alt](src)`; `title` included when present |
| `ul` / `ol` / `li` | `-` / `1.` items, nesting indented, `start=` honored |
| `blockquote` | `>` prefixed lines |
| `table` | GFM pipe table; see [Tables](#tables) |
| `dl` / `dt` / `dd` | definition list; the term, then `: definition` attached |
| `hr`, `br` | `---`, backslash hard break |
| `div`, `section`, … | invisible; children render as blocks |
| `span`, `mark`, … | invisible; children flow through inline |
| `script`, `style`, `head`, … | dropped |
| everything else | falls back to its HTML, which Markdown permits |

The tables driving this (`INLINE_WRAPPERS`, `CONTAINER_TAGS`,
`TRANSPARENT_TAGS`, `DROP_TAGS`, `HEADING_TAGS`) are module constants, so
teaching the renderer a new element is one dict or set entry.

#### Element tables

These three sets decide what happens to an element with no Markdown
equivalent. Everything absent from all of them falls back to its HTML.

| Constant | Effect | Elements |
| --- | --- | --- |
| `CONTAINER_TAGS` | rendered as blocks, the element disappears | `article`, `aside`, `body`, `details`, `dialog`, `div`, `fieldset`, `figure`, `footer`, `form`, `header`, `hgroup`, `html`, `main`, `menu`, `nav`, `search`, `section` |
| `TRANSPARENT_TAGS` | children flow through inline, no HTML fallback | `abbr`, `bdi`, `bdo`, `cite`, `data`, `dfn`, `kbd`, `label`, `mark`, `output`, `q`, `rp`, `rt`, `ruby`, `samp`, `slot`, `small`, `span`, `sub`, `sup`, `time`, `u`, `var` |
| `DROP_TAGS` | removed with their content | `head`, `link`, `meta`, `script`, `style`, `template`, `title` |

`INLINE_WRAPPERS` maps an inline element to a symmetric Markdown wrapper:

| Tag | Renders `x` as |
| --- | --- |
| `b` | `**x**` |
| `del` | `~~x~~` |
| `em` | `*x*` |
| `i` | `*x*` |
| `ins` | `x` (unwrapped) |
| `s` | `~~x~~` |
| `strong` | `**x**` |

`HEADING_TAGS` maps a heading to its prefix:

| Tag | Prefix |
| --- | --- |
| `h1` | `#` |
| `h2` | `##` |
| `h3` | `###` |
| `h4` | `####` |
| `h5` | `#####` |
| `h6` | `######` |

### Tables

Tables get the fullest treatment, because they are where HTML-to-Markdown
conversions usually fall apart:

```python
Table(
    Caption("Prices"),
    Thead(Tr(Th("Item"), Th("Cost", style={"text_align": "right"}))),
    Tbody(Tr(Td("Apple"), Td("1"))),
)
```

```markdown
Prices

| Item | Cost |
| --- | --: |
| Apple | 1 |
```

- **Alignment** comes from `text-align` styles (string or mapping) or the
  legacy `align` attribute, and round-trips: `from_markdown` keeps the
  alignment markdown-it records, and `to_markdown` emits it back as
  `:--` / `:-:` / `--:`.
- **`thead` / `tbody` / `tfoot` render in that order**, matching how HTML
  displays them, even when the source declares them differently.
- **A caption** becomes a paragraph above the table, because GFM has no caption.
- **A headerless table** gets an empty header row, since GFM requires one;
  the first data row is not promoted.
- **Hard breaks and block content in cells** flatten to `<br>`, which GFM
  permits, so a cell can never split its own row.
- **Nested tables** stay inside their cell as HTML, exactly once.
- **`colspan`/`rowspan` have no GFM form**, so such tables fall back to
  their HTML rather than silently misplacing data.

### Fences and code

Content containing backticks can't break out of its own code span or fence, because
the marker grows past it:

`````python
to_markdown(Pre("a ``` b"))           # '````\na ``` b\n````'
to_markdown(P(Code("uses ` tick")))   # '`` uses ` tick ``'
`````

### Lossy on purpose

Markdown has no home for `class`, `id`, `data-*`, or most other attributes,
so they are dropped. Text is emitted verbatim, not escaped, so content that
looks like Markdown syntax will be treated as Markdown by whatever renders
the output. Treat `to_markdown()` as a conversion, not an encoding:
round-trips preserve structure, not bytes.

## Reading Markdown

`from_markdown()` returns the same kind of tree as `from_html()`: typed
element classes, not a foreign AST. It deliberately contains no Markdown
parser: markdown-it-py renders CommonMark plus GFM tables and strikethrough,
and the HTML comes back through `parse()`.

```python
tree = from_markdown("# Title\n\nBody text.")
tree[0].tag          # 'h1'
tree[0].text         # 'Title'
```

A single-root document unwraps to the item itself, like `from_html()`;
anything else is a list.

### The tree is the point

Everything that works on a parsed HTML tree works on a parsed Markdown
document, including searching, editing, and serializing:

```python
doc = from_markdown("# Guide\n\nSee [the docs](/docs) and [the api](/api).")
[(a.text, a.attrs["href"]) for a in doc[1].find_all("a")]
# [('the docs', '/docs'), ('the api', '/api')]

from_markdown("# Title").model_dump()   # {'tag': 'h1', ...}
```

And because `to_markdown()` accepts the same tree back, Markdown documents
can be edited *structurally*, with no regexes over source text:

```python
doc = from_markdown("# Title\n\n## Section\n\nBody.")
for item in doc:
    if item.tag in ("h1", "h2"):
        item.tag = f"h{int(item.tag[1]) + 1}"   # demote one level

to_markdown(doc)   # '## Title\n\n### Section\n\nBody.'
```

### Fidelity

Reading then writing is stable: a second round trip reproduces the first,
and fenced code keeps its language and content exactly:

````python
doc = from_markdown("```python\nif a < b:\n    go()\n```")
doc.find("code").attrs["class"]   # 'language-python'
to_markdown(doc)                  # the same fence back, byte for byte
````

Alignment in tables survives the loop too. See [Tables](#tables).


---

<!-- django -->

# Django

Django is optional. Only `django_div.django` imports it, so installing
django-div in a non-Django project pulls in nothing.

## Escaping, both directions

Rendering escapes text and attribute values, so output is safe markup by
construction. A tag can go straight into a template context with no `|safe`:

```django
{{ card }}
```

Why `__html__` alone wasn't enough

Django's template engine calls `str()` on any value that isn't already a
string *before* it looks for `__html__`. A plain `str` return would have
been escaped, so `__str__` itself reports the result as safe.

Interop runs the other way too. Anything carrying `__html__` (a
`SafeString`, a `markupsafe.Markup`, a rendered form) passes through a tag
unescaped, while ordinary strings are still escaped:

```python
Div(mark_safe("<b>bold</b>"))   # <div><b>bold</b></div>
Div("<b>bold</b>")              # <div>&lt;b&gt;bold&lt;/b&gt;</div>
Div(form.as_p())                # the form's own markup, intact
```

Lazy objects resolve correctly, so translations work:

```python
Div(gettext_lazy("Hello"))      # <div>Hello</div>
```

### Component return values

Plain-string component results are escaped, just like text children.
For example, returning `"<b>Hello</b>"` produces
`&lt;b&gt;Hello&lt;/b&gt;`. Return elements for structured HTML, or use
`Raw(content=trusted_html)` for intentional, trusted markup. Objects with
`__html__`, including Django `SafeString`, retain their trusted status.

This changes the previous behavior that treated all component string
results as safe HTML. Existing components returning HTML strings should
return elements or explicitly trusted markup instead.

## Components as templates

`DjangoDivTemplates` is a template backend whose templates are Python
callables. Register it alongside your existing engines:

settings.py

```python
TEMPLATES = [
    {
        "BACKEND": "django_div.django.DjangoDivTemplates",
        "NAME": "django_div",
        "DIRS": [],
        "APP_DIRS": False,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
            ],
        },
    },
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        # ... your usual configuration, untouched
    },
]
```

A component is a callable, usually returning an `HtmlItem`, addressed by its
dotted path. Plain-string results are escaped; explicitly trusted markup is
preserved as described above:

myapp/components.py

```python
from django_div import H1, Div, Li, P, Ul


def home(title, items, **context):
    return Div(
        H1(title),
        Ul(Li(item) for item in items),
        class_="page",
    )
```

myapp/views.py

```python
from django.shortcuts import render


def home_view(request):
    return render(request, "myapp.components.home", {
        "title": "Hi",
        "items": ["one", "two"],
    })
```

Because it is a normal backend, `render()`, `render_to_string()`,
`get_template()`, and the generic class-based views all work unchanged.

### Context handling

A component receives the context as keyword arguments:

- Declare `**kwargs` and you get the whole context.
- Name your parameters and you get only those.

```python
def greet(name="world"):        # ignores request, user, csrf_token, ...
    return P(f"Hello, {name}")
```

That second case matters. Context processors add `request`, `user`, `perms`,
and more to every render; without the filtering, adding one would break every
component signature at once.

### Incremental adoption

A component that can't be resolved raises `TemplateDoesNotExist`, so Django's
loader falls through to the next engine. Ordinary `.html` templates keep
working, and you can convert one view at a time.

Template names are import paths

`"myapp.components.home"` is imported and called. Never build a template
name from user input. That is an arbitrary-import primitive.

## Without the template layer

For views that build their own markup:

```python
from django_div import H1, Div, Form, Input
from django_div.django import as_response, csrf_input


def index(request):
    return as_response(Div(H1("Hi")))


def search(request):
    return as_response(
        Form(
            csrf_input(request),
            Input(name="q", placeholder="Search"),
            method="post",
        )
    )
```

`as_response()` passes extra keyword arguments to `HttpResponse`, so
`status=` and `content_type=` work as usual.

`csrf_input()` produces the hidden token field using Django's own machinery,
so it stays correct if that changes.

## Rendering a tag yourself

`render()` returns a `SafeString` when Django is installed, and a plain `str`
otherwise:

```python
Div("hi").render()
```

## What this is not

django-div does not replace Django's template language, and does not try to.
There is no inheritance, no `{% block %}`, and no partial loading. A
component is a function, so composition is function calls and default
arguments instead.

If you want template inheritance, keep those pages in Django templates and
use django-div for the parts that benefit from being Python.

## Components returning siblings

Return a `Fragment` to render siblings without an extra wrapper:

```python
from django_div import Fragment, H1, P


def content(title):
    return Fragment(H1(title), P("Body"))
```

It works with the template backend and `as_response()` just like a tag.
The backend caches signature metadata for ordinary functions, up to 256
entries. It still calls the component and builds its output for each render.


---

<!-- cookbook -->

# Cookbook

Practical recipes, none of them Django-specific. The Python recipes are covered by
`tests/test_cookbook.py`; browser-side JavaScript illustrates how to use the
rendered markup.

For Django-specific recipes, see the [Django cookbook](../django-cookbook/).

## Building

### A reusable component

A component is a function. There is no registry, no base class, and no
special syntax. Composition is a function call.

```python
def card(title, *body, href=None):
    heading = A(title, href=href) if href else title
    return Div(H2(heading), Div(*body, class_="card-body"), class_="card")

card("Hello", P("Body"), href="/x")
```

```html
<div class="card"><h2><a href="/x">Hello</a></h2><div class="card-body"><p>Body</p></div></div>
```

Taking `*body` and passing it through keeps the caller's syntax identical to
a built-in element's.

### Reusable button variants

Use `with_attrs()` to derive variants from a configured element:

```python
from django_div import Button

base = Button("Save", class_="btn", type="submit")
primary = base.with_attrs(class_="btn primary", disabled=True)
```

```html
<button class="btn primary" type="submit" disabled>Save</button>
```

`base` still has `class="btn"` and no `disabled` attribute. Classes are
replaced as a whole, so include any base classes you want to keep. Pass
`None` to omit an attribute on render. The attribute dictionary and child
list are copied, while existing child objects and nested attribute values
remain shared.

### A disclosure with matching ARIA state

Use the same Python flag to describe whether a panel is expanded and
whether its content is hidden:

```python
from django_div import Button, Div, Fragment


def disclosure(content, *, expanded=False):
    return Fragment(
        Button(
            "Details", type="button", aria_controls="details",
            aria_expanded=expanded,
        ),
        Div(content, id="details", hidden=not expanded),
    )


disclosure("More information")
```

```html
<button type="button" aria-controls="details" aria-expanded="false">Details</button><div id="details" hidden>More information</div>
```

ARIA booleans render as explicit `"true"` or `"false"`; HTML booleans such
as `hidden` render bare when true and disappear when false. This recipe
sets the initial state. If JavaScript toggles the panel, update both
`aria-expanded` and `hidden`. Give each panel a unique ID when rendering
multiple disclosures.

### A whole document

A doctype isn't an element, so it has its own item class. `Doctype()`
renders the HTML5 doctype, and a document is a list:

```python
def document(title, *body, lang="en"):
    return [
        Doctype(),
        Html(Head(Meta(charset="utf-8"), Title(title)), Body(*body), lang=lang),
    ]

def render(items):
    return "".join(str(item) for item in items)

render(document("Home", H1("Hi")))
```

```html
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8" /><title>Home</title></head><body><h1>Hi</h1></body></html>
```

### HTML templates for JavaScript

Use `Template` to hold HTML that JavaScript can clone and insert later.
Build its contents with elements as usual:

```python
from django_div import Div, Span, Template

template = Template(
    Div(Span("Hello"), class_="card"),
    id="card-template",
)
```

For an existing trusted HTML string, wrap the markup in `Raw`:

```python
from django_div import Raw, Template

template = Template(
    Raw(content='<div class="card"><span>Hello</span></div>'),
    id="card-template",
)
```

Both produce the same HTML when rendered with `str(template)`:

```html
<template id="card-template"><div class="card"><span>Hello</span></div></template>
```

Once the template is in the document, JavaScript can insert its contents:

```javascript
const template = document.querySelector("#card-template");
document.body.append(template.content.cloneNode(true));
```

Ordinary string children are still escaped inside `Template`. Use `Raw`
only for trusted markup, never untrusted user input. Placeholders such as
`{{ name }}` remain literal; django-div does not evaluate them.

### A table from data

```python
def data_table(rows, columns):
    return Table(
        Thead(Tr(Th(column) for column in columns)),
        Tbody(Tr(Td(row[column]) for column in columns) for row in rows),
    )

data_table([{"name": "Ana", "age": 33}], ["name", "age"])
```

```html
<table><thead><tr><th>name</th><th>age</th></tr></thead><tbody><tr><td>Ana</td><td>33</td></tr></tbody></table>
```

Nested generators work because each one is flattened as it is consumed.

### Navigation with an active item

A `class` mapping turns a condition into a class, and an all-false mapping
drops the attribute rather than emitting `class=""`.

```python
def nav(links, current):
    return Nav(
        Ul(Li(A(label, href=url, class_={"active": url == current}))
           for label, url in links)
    )

nav([("Home", "/"), ("Docs", "/docs/")], "/docs/")
```

```html
<nav><ul><li><a href="/">Home</a></li><li><a href="/docs/" class="active">Docs</a></li></ul></nav>
```

A generator can't sit beside a keyword argument

This is a Python rule, not a django-div one:

```python
Ul(Li(x) for x in items, class_="errors")   # SyntaxError
```

Add brackets and it's fine:

```python
Ul([Li(x) for x in items], class_="errors")
```

### Custom elements and web components

```python
MyWidget = tag_class("my-widget")
MyWidget("hi", data_state="ready")
```

```html
<my-widget data-state="ready">hi</my-widget>
```

`tag_class()` registers the result **globally**, in `TAG_CLASSES`, so parsing
produces that class too. That is the point, but it means the registry grows at
runtime. `BUILTIN_TAGS` is the fixed set this library ships. For a one-off
that shouldn't be registered, `Tag("my-widget", ...)` skips it.

### Passing data to JavaScript

Use `JsonScript` to pass data to JavaScript. It escapes characters that could
close the script element while preserving the original JSON values:

```python
from django_div import JsonScript

JsonScript({"a": "</script>"}, id="config")
```

```html
<script type="application/json" id="config">{"a":"\u003c/script\u003e"}</script>
```

Read the data after the element is in the document:

```javascript
const config = JSON.parse(document.getElementById("config").textContent);
```

`JsonScript` accepts dictionaries, lists, and nested Pydantic models.
Models use their field aliases and JSON-compatible values; `None` is
preserved as JSON `null`. No Django dependency is required.

Use this helper for data instead of interpolating values into executable
`Script` content. Plain HTML escaping is unsuitable inside a script element.

### Open Graph metadata

Group page metadata in a reusable function. `Fragment` emits sibling meta
elements without adding a wrapper. Use `page_type` to avoid shadowing
Python's built-in `type`; the metadata property remains `og:type`.

```python
from django_div import Fragment, Head, Meta, Title


def open_graph(*, title, url, image, description, page_type="website"):
    return Fragment(
        Meta(property="og:title", content=title),
        Meta(property="og:type", content=page_type),
        Meta(property="og:url", content=url),
        Meta(property="og:image", content=image),
        Meta(property="og:description", content=description),
    )


head = Head(
    Title("Introducing django-div"),
    open_graph(
        title="Introducing django-div",
        url="https://example.com/posts/django-div/",
        image="https://example.com/images/django-div.png",
        description="Build and parse HTML in Python.",
        page_type="article",
    ),
)
```

`str(head)` produces the following HTML (line breaks added for readability):

```html
<head>
  <title>Introducing django-div</title>
  <meta property="og:title" content="Introducing django-div" />
  <meta property="og:type" content="article" />
  <meta property="og:url" content="https://example.com/posts/django-div/" />
  <meta property="og:image" content="https://example.com/images/django-div.png" />
  <meta property="og:description" content="Build and parse HTML in Python." />
</head>
```

Use absolute URLs for the page and image. Values are escaped as ordinary
attributes, so no `Raw` wrapper is needed. Omit `page_type` to use the default
`"website"`. Extend the function with metadata your project needs, such as
`og:site_name` or `og:image:alt`. See the [Open Graph protocol](https://ogp.me/).

### JSON-LD from a Pydantic model

Schema.org markup is JSON in a `<script>`, and a `<script>` is raw text: the
parser reads to the closing tag without decoding entities, so a name or
description containing `</script>` would close the tag early and the rest of
the payload would land on the page as live markup. `JsonLd` writes the
dangerous characters as the `\uXXXX` escapes JSON already understands, which
changes no data and makes that impossible.

Any Pydantic model works; nothing has to inherit from anything in
django-div. `@context` and `@type` are not Python names, so declare them as
aliases, which is also how you reach schema.org's camelCase properties like
`sameAs`:

```python
from pydantic import BaseModel, ConfigDict, Field

from django_div import Head, JsonLd, Title


class Organization(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    context: str = Field("https://schema.org", alias="@context")
    type: str = Field("Organization", alias="@type")
    name: str
    url: str
    logo: str | None = None
    same_as: list[str] | None = Field(None, alias="sameAs")


head = Head(
    Title("Acme"),
    JsonLd(Organization(name="Acme", url="https://acme.example")),
)
```

Models are dumped by alias with `None` dropped, so `logo` and `same_as` never
render. A JSON-LD null is not a value, so dropping it is what the format
means anyway. To dump on other terms, call `model_dump()` yourself and pass
the dict.

If you write a lot of these, the two constant fields are worth a base class
of your own -- but that is your vocabulary to shape, not something django-div
should decide for you.

Pass a list to emit several objects at once, and read one back out of a page
with `json.loads(tag.text)`:

```python
import json

from django_div import from_html

page = from_html(str(head))
data = json.loads(page.find("script", type="application/ld+json").text)
```

### SVG icons

SVG elements aren't generated, because SVG's `<text>` would collide with the
`Text` model. Build the ones you need:

```python
Svg = tag_class("svg")
Use = tag_class("use")

def icon(name, size=16):
    return Svg(
        Use(href=f"/static/icons.svg#{name}"),
        width=size, height=size, aria_hidden="true",
    )
```

```html
<svg width="16" height="16" aria-hidden="true"><use href="/static/icons.svg#check"></use></svg>
```

### Inline SVG shapes

SVG attribute names are case-sensitive, and a name without an underscore
passes through untouched, so `viewBox` renders as `viewBox`. Underscores
still become hyphens, which is what `stroke_width` needs:

```python
Svg = tag_class("svg")
Circle = tag_class("circle")
Path = tag_class("path")

check = Svg(
    Circle(cx="12", cy="12", r="10", fill="none"),
    Path(d="M8 12l3 3 5-6"),
    viewBox="0 0 24 24", width=24, height=24,
    stroke="currentColor", stroke_width="2", aria_hidden="true",
)
```

```html
<svg viewBox="0 0 24 24" width="24" height="24" stroke="currentColor" stroke-width="2" aria-hidden="true"><circle cx="12" cy="12" r="10" fill="none"></circle><path d="M8 12l3 3 5-6"></path></svg>
```

Shapes render as a full open and close pair, never self-closed, because only
HTML void elements self-close. A browser accepts `<path></path>` in inline
SVG.

Parsing SVG loses the attribute case

Building SVG keeps `viewBox`. Reading it back does not: an HTML parser
folds every attribute name to lowercase, so `from_html` returns
`viewbox`, which a browser ignores. The same applies to
`preserveAspectRatio`, `gradientUnits`, and the other camelCase names.
Treat SVG as write-only, or repair the names yourself after a parse.

### XML, not just HTML

`Tag` doesn't care whether a name is HTML, so feeds and other XML work:

```python
Tag("rss",
    Tag("channel", Tag("title", "News"), Tag("item", Tag("title", "First"))),
    version="2.0")
```

```html
<rss version="2.0"><channel><title>News</title><item><title>First</title></item></channel></rss>
```

Note

Only HTML void elements self-close, and HTML escaping rules are applied.
For heavy XML work a dedicated library is a better fit.

## Parsing

These need the `parse` extra.

### Extract every link

```python
page = from_html(markup)
[(a.text, a.attrs["href"]) for a in page.find_all("a")]
```

```python
[("A", "/a"), ("B", "/b")]
```

### Find links by class token

Pass a predicate when a class can appear alongside other classes. Keyword
attributes narrow the results using their existing exact-match behavior:

```python
from django_div import from_html

page = from_html(
    '<div><a class="external featured" target="_blank" href="/one">One</a>'
    '<a class="external" href="/two">Two</a></div>'
)
links = page.find_all(
    lambda node: node.tag == "a" and node.has_class("external"),
    target="_blank",
)
[link.attrs["href"] for link in links]
# ['/one']
```

`find()` takes the same predicate and stops at the first match;
`iter_find()` yields matches lazily. All three search descendant tags in
document order, excluding the root. To compare a complete class attribute
instead, continue using `find_all("a", class_="external")`.

### Make relative URLs absolute

```python
from urllib.parse import urljoin

def absolutize(tree, base):
    for link in tree.find_all("a"):
        if "href" in link.attrs:
            link.attrs["href"] = urljoin(base, link.attrs["href"])
    return tree

absolutize(from_html('<div><a href="/a">A</a></div>'), "https://example.test/")
```

```html
<div><a href="https://example.test/a">A</a></div>
```

### Build a table of contents

```python
def table_of_contents(tree, levels=("h2", "h3")):
    return Ul(
        Li(A(heading.text, href="#" + heading.attrs["id"]))
        for heading in tree.find_all()
        if heading.tag in levels and "id" in heading.attrs
    )
```

```html
<ul><li><a href="#a">A</a></li><li><a href="#b">B</a></li></ul>
```

Parsing and building in the same expression is the point: the input is HTML
and so is the output.

### Scrape a table into dicts

```python
def cells(row):
    return [cell.text.strip() for cell in row.find_all() if cell.tag in {"th", "td"}]

def table_to_dicts(table):
    rows = table.find_all("tr")
    headers = cells(rows[0])
    return [dict(zip(headers, cells(row))) for row in rows[1:]]
```

```python
[{"name": "Ana", "age": "33"}]
```

### Keep only certain elements

Transform a copy to remove unwanted nodes and unwrap other containers.
Children are processed before parents; returning a fragment preserves
already-filtered children without their original wrapper. The source remains
unchanged. Import `Fragment`, `Tag`, `Text`, and `parse` from `django_div`.

```python
KEEP = {"p", "b", "i", "em", "strong", "a", "ul", "ol", "li", "code", "br"}
KEEP_ATTRS = {"a": {"href", "title"}}
DROP_ENTIRELY = {"script", "style"}

def keep_node(item):
    if isinstance(item, (Text, Fragment)):
        return item
    if isinstance(item, Tag):
        if item.tag in DROP_ENTIRELY:
            return None
        if item.tag not in KEEP:
            return Fragment(item.children)
        item.attrs = {
            name: value for name, value in item.attrs.items()
            if name in KEEP_ATTRS.get(item.tag, set())
        }
        return item
    return None


def keep_only(items):
    return Fragment(items).transform(keep_node)
```

```python
items = parse('<p onclick="evil()">ok <script>alert(1)</script><b>b</b></p>')
str(keep_only(items))
# <p>ok <b>b</b></p>
```

This is not a sanitizer

It is a shape filter for content you already trust: trimming a CMS
export, normalizing pasted markup. It is **not** an XSS defense. Real
sanitization has to handle `javascript:` URLs, CSS escapes, mutation
XSS, and namespace confusion. For untrusted input use
[nh3](https://pypi.org/project/nh3/) or
[bleach](https://pypi.org/project/bleach/).

Note that `DROP_ENTIRELY` exists because unwrapping a `<script>` would
keep its *code* as visible text.

### Readable text

`.text` concatenates, matching the DOM's `textContent`, so adjacent blocks
run together:

```python
tree = from_html("<article><h1>Title</h1><p>one two</p></article>")
tree.text          # 'Titleone two'
```

For search indexing or summaries, join trimmed text nodes:

```python
tree.get_text(" ", strip=True)   # 'Title one two'
```

The separator goes between every text node, including inline elements;
choose it for the output you need. `.text` keeps its original behavior.

### Pretty-print a tree

Rendering has no indentation, by design. When you want it for debugging:

```python
def pretty(item, indent=0):
    pad = "  " * indent
    if not isinstance(item, Tag):
        text = str(item).strip()
        return [pad + text] if text else []
    if item.is_void:
        return [pad + str(item)]
    opening = str(item).split(">", 1)[0] + ">"
    lines = [pad + opening]
    for child in item.children:
        lines += pretty(child, indent + 1)
    return [*lines, pad + f"</{item.tag}>"]
```

```text
<div>
  <p>
    hi
  </p>
</div>
```

## Markdown

The same tree renders as Markdown, and Markdown reads back in. Those
recipes (changelog generation, link hardening, code-block extraction,
document merging) have their own page: the
[Markdown cookbook](../markdown-cookbook/).

## Serializing

### Cache a parsed page

Parsing is the expensive part. Serialize once, reload cheaply:

```python
tree = from_html(response.text)
cache.set("page", tree.model_dump_json())

tree = Tag.model_validate_json(cache.get("page"))
```

Element classes survive the round trip, so `find_all()` and friends still
work on the way back.

### Compare two pages structurally

Models compare by value, so equality ignores nothing that matters and
nothing that doesn't:

```python
from_html("<div><p>x</p></div>") == from_html("<div><p>x</p></div>")   # True
from_html("<div><p>x</p></div>") == from_html("<div><p>y</p></div>")   # False
```

### Assert on structure, not strings

The most useful thing `from_html()` does in a test suite is let you stop
matching substrings:

```python
def test_search_form():
    page = from_html(response.text)
    assert page.find("input", name="q") is not None
    assert page.find("button").text == "Go"
```

That survives reformatting, attribute reordering, and added wrappers, all of
which break `assert '<input name="q">' in html`.


---

<!-- django-cookbook -->

# Django cookbook

Recipes for using django-div inside a Django project. Every example is
executed by `tests/test_cookbook.py`.

See [Django](../django/) for the template backend and escaping rules, and the
[Cookbook](../cookbook/) for recipes that don't need Django.

## Template tags

### A simple tag that returns markup

The most incremental way to adopt django-div: keep your templates, replace
one widget.

myapp/templatetags/ui.py

```python
from django import template
from django_div import Span

register = template.Library()


@register.simple_tag
def badge(text, tone="info"):
    return Span(text, class_=["badge", f"badge-{tone}"]).render()
```

```django
{% load ui %}
{% badge "New" tone="success" %}
```

```html
<span class="badge badge-success">New</span>
```

`.render()` returns a `SafeString`, so `simple_tag` won't escape it.

Inclusion tags without the template

`@register.inclusion_tag` exists to render a small template with a small
context. A `simple_tag` returning a component does the same job with no
second file and no template lookup.

### Passing a tag through the context

A view can build a component and hand it to an ordinary template. No `|safe`
is needed. See [escaping](../django/#escaping-both-directions).

```python
def dashboard(request):
    return render(request, "dashboard.html", {"card": Div(H2("Hi"), class_="card")})
```

```django
{{ card }}
```

```html
<div class="card"><h2>Hi</h2></div>
```

## Forms

### Render a field with its label and errors

```python
def render_field(field):
    return Div(
        Label(field.label, for_=field.id_for_label),
        Raw(content=str(field)),
        field.errors and Ul([Li(error) for error in field.errors], class_="errors"),
        class_="field",
    )
```

```html
<div class="field"><label for="id_email">Email</label><input type="email" name="email" ...><ul class="errors"><li>Enter a valid email address.</li></ul></div>
```

Two things are carrying the weight here:

- `Raw(content=str(field))` emits the widget's own markup untouched. You
  could also pass `field` directly, since Django's rendered widget carries
  `__html__`.
- `field.errors and ...` drops the whole list when there are no errors,
  because `False` children disappear.

### Add a CSS class to a widget

Rather than rebuilding the widget or editing `attrs` at form-definition
time, parse what Django produced and adjust it:

```python
def with_class(widget_html, css_class):
    tree = from_html(str(widget_html))
    existing = tree.attrs.get("class")
    tree.attrs["class"] = " ".join(filter(None, [existing, css_class]))
    return tree

with_class(form["email"], "form-control")
```

```html
<input type="email" name="email" ... class="form-control" />
```

This works on any widget, including third-party ones you don't control.

Note

Boolean attributes come back from the parser with an empty value, so
`required` re-renders as `required=""`. That's equivalent HTML, not a
change in meaning.

### A form with CSRF

```python
from django_div.django import csrf_input

Form(csrf_input(request), Input(name="q"), Button("Go"), method="post")
```

```html
<form method="post"><input type="hidden" name="csrfmiddlewaretoken" value="..."><input name="q" /><button>Go</button></form>
```

## Views

### Respond without a template

```python
from django_div.django import as_response

def index(request):
    return as_response(Div(H1("Hi")))
```

`as_response()` forwards keyword arguments to `HttpResponse`, so
`status=404` and `content_type=` work as usual.

### htmx partials

htmx wants a fragment, which is exactly what a component already is. `hx_*`
attributes normalize to `hx-*`.

```python
def item_row(item):
    return Tr(
        Td(item["name"]),
        Td(Button("Delete",
                  hx_delete=f"/items/{item['id']}/",
                  hx_target="closest tr",
                  hx_swap="outerHTML")),
        id=f"item-{item['id']}",
    )


def delete_item(request, pk):
    Item.objects.filter(pk=pk).delete()
    return HttpResponse("")          # htmx swaps the row away
```

```html
<tr id="item-3"><td>Ana</td><td><button hx-delete="/items/3/" hx-target="closest tr" hx-swap="outerHTML">Delete</button></td></tr>
```

The same function serves the full page and the partial, so the two can't
drift apart.

## Components

### Messages

```python
def alerts(messages):
    return Div(
        [Div(message, class_=["alert", f"alert-{level}"]) for level, message in messages],
        class_="messages",
    )

alerts((m.level_tag, m.message) for m in get_messages(request))
```

```html
<div class="messages"><div class="alert alert-info">Saved</div></div>
```

### Pagination

```python
def pagination(number, num_pages, base="?page="):
    return Nav(
        Ul(
            Li(A("Previous", href=f"{base}{number - 1}")) if number > 1 else None,
            [Li(A(str(n), href=f"{base}{n}", class_={"current": n == number}))
             for n in range(1, num_pages + 1)],
            Li(A("Next", href=f"{base}{number + 1}")) if number < num_pages else None,
        ),
        class_="pagination",
    )

pagination(page_obj.number, page_obj.paginator.num_pages)
```

The `if ... else None` arms disappear on the first and last page, which in a
template would be two `{% if %}` blocks.

### Breadcrumbs

```python
def breadcrumbs(trail):
    items = []
    for index, (label, url) in enumerate(trail):
        last = index == len(trail) - 1
        items.append(Li(label if last else A(label, href=url), class_={"active": last}))
    return Nav(Ol(items, class_="breadcrumb"), aria_label="Breadcrumb")

breadcrumbs([("Home", "/"), ("Building", None)])
```

```html
<nav aria-label="Breadcrumb"><ol class="breadcrumb"><li><a href="/">Home</a></li><li class="active">Building</li></ol></nav>
```

## Passing data to JavaScript

Use `JsonScript` inside a component to pass browser configuration safely.
It supports nested Pydantic models and preserves `None` as JSON `null`.
See the [complete recipe](../cookbook/#passing-data-to-javascript) for the
Python, rendered HTML, and JavaScript reader. The helper works without Django.

## Email

HTML email wants a full document and inline styles:

```python
from django.core.mail import EmailMultiAlternatives

def receipt_email(order, to):
    html = render(document(
        "Receipt",
        P(f"Hi {order.customer}", style={"font_family": "sans-serif"}),
    ))
    message = EmailMultiAlternatives("Your receipt", strip_tags(html), to=[to])
    message.attach_alternative(html, "text/html")
    return message
```

`document()` and `render()` are from the
[Cookbook](../cookbook/#a-whole-document).

## Testing

### Assert on structure

```python
def test_search_page(client):
    page = from_html(client.get("/search/").content.decode())

    assert page.find("input", name="q") is not None
    assert [a.text for a in page.find_all("a", class_="result")] == ["First", "Second"]
```

Substring assertions break when markup is reformatted or an attribute is
reordered. Structural ones don't.

### Test a component directly

Components are functions returning values, so most of the time you don't
need a request, a client, or a database at all:

```python
def test_badge():
    assert str(badge("New", tone="success")) == (
        '<span class="badge badge-success">New</span>'
    )
```


---

<!-- markdown-cookbook -->

# Markdown cookbook

Recipes built on `to_markdown()` and `from_markdown()`. Every example is
executed by `tests/test_markdown_cookbook.py`.

See [Markdown](../markdown/) for the mapping rules, and the
[Cookbook](../cookbook/) for HTML-side recipes.

## Writing

### One builder, two formats

A tree doesn't care which renderer consumes it, so the same function serves
the page as HTML and the export as Markdown:

```python
from django_div.markdown import to_markdown

table = data_table([{"name": "Ana", "age": 33}], ["name", "age"])
str(table)          # <table>...</table>              for the page
to_markdown(table)  # | name | age | ...              for the export
```

`data_table` is the [cookbook recipe](../cookbook/#a-table-from-data),
unchanged.

### A changelog from data

Markdown documents are trees too, so release notes come from the same
composition as any page:

```python
def changelog(releases):
    blocks = [H1("Changelog")]
    for version, date, changes in releases:
        blocks.append(H2(f"{version} ({date})"))
        blocks.append(Ul(Li(change) for change in changes))
    return to_markdown(blocks)

changelog([("1.1.0", "2026-08-01", ["Added X", "Fixed Y"])])
```

```markdown
# Changelog

## 1.1.0 (2026-08-01)

- Added X
- Fixed Y
```

### Convert scraped HTML to Markdown

```python
to_markdown(from_html("<article><h1>Post</h1><p>Text with <em>emphasis</em>.</p></article>"))
# '# Post\n\nText with *emphasis*.'
```

Feeding an LLM, archiving a page, filling a docs pipeline: one line. This
project's own `llms.txt` generator does exactly this conversion.

## Reading

### Render user Markdown, hardening links on the way

Comments, bios, and READMEs arrive as Markdown; the page wants HTML with
house rules applied. Reading into a tree gives you an editing step between
the two:

```python
from django_div.markdown import from_markdown

def render_user_markdown(text):
    items = from_markdown(text)
    items = items if isinstance(items, list) else [items]
    for item in items:
        if not isinstance(item, Tag):
            continue
        for link in item.find_all("a"):
            href = link.attrs.get("href", "")
            if href.startswith(("http://", "https://")):
                link.attrs["rel"] = "noopener"
                link.attrs["target"] = "_blank"
    return "".join(str(item) for item in items)
```

```python
render_user_markdown("[in](/x) and [out](https://ex.test)")
# <p><a href="/x">in</a> and
#    <a href="https://ex.test" rel="noopener" target="_blank">out</a></p>
```

### Markdown into a full page

The read tree drops straight into a layout, so a Markdown file becomes a
finished document:

```python
def page(markdown_text, *, title):
    items = from_markdown(markdown_text)
    items = items if isinstance(items, list) else [items]
    return "".join(str(part) for part in [
        Doctype(),
        Html(
            Head(Meta(charset="utf-8"), Title(title)),
            Body(Div(items, class_="content")),
            lang="en",
        ),
    ])

page("# Hello\n\nWorld.", title="Hi")
# <!DOCTYPE html><html lang="en">...<div class="content"><h1>Hello</h1><p>World.</p></div>...
```

### Outline a document

```python
HEADINGS = {"h1", "h2", "h3", "h4", "h5", "h6"}

def outline(markdown_text):
    items = from_markdown(markdown_text)
    items = items if isinstance(items, list) else [items]
    return [
        (int(item.tag[1]), item.text)
        for item in items
        if isinstance(item, Tag) and item.tag in HEADINGS
    ]

outline("# A\n\ntext\n\n## B\n\n### C")   # [(1, 'A'), (2, 'B'), (3, 'C')]
```

### Extract every code block

Pull `(language, source)` pairs out of a document, the first step of
"run the examples in our docs as tests", which this project does:

````python
def code_blocks(markdown_text):
    items = from_markdown(markdown_text)
    items = items if isinstance(items, list) else [items]
    found = []
    for item in items:
        if not (isinstance(item, Tag) and item.tag == "pre"):
            continue
        code = item.find("code") or item
        language = str(code.attrs.get("class", "")).removeprefix("language-")
        found.append((language, code.text.strip("\n")))
    return found

code_blocks("intro\n\n```python\nprint('hi')\n```\n\n```sql\nSELECT 1\n```")
# [('python', "print('hi')"), ('sql', 'SELECT 1')]
````

### Audit images for missing alt text

An accessibility check over content that lives as Markdown:

```python
def images_missing_alt(markdown_text):
    items = from_markdown(markdown_text)
    items = items if isinstance(items, list) else [items]
    return [
        img.attrs.get("src", "")
        for item in items
        if isinstance(item, Tag)
        for img in item.find_all("img")
        if not img.attrs.get("alt")
    ]

images_missing_alt("![A cat](cat.png)\n\n![](bare.png)")   # ['bare.png']
```

## Round-tripping

### Merge documents, normalizing heading levels

Concatenating Markdown files naively produces colliding `#` levels. Read
each one, demote its headings under a section heading, and write the result
back out:

```python
def merged(docs):
    blocks = []
    for title, text in docs:
        blocks.append(H2(title))
        items = from_markdown(text)
        items = items if isinstance(items, list) else [items]
        for item in items:
            if isinstance(item, Tag) and item.tag in HEADINGS:
                item.tag = f"h{min(int(item.tag[1]) + 2, 6)}"
            blocks.append(item)
    return to_markdown([H1("Handbook"), *blocks])

merged([("Intro", "# Welcome\n\nHi."), ("Usage", "# Start")])
```

```markdown
# Handbook

## Intro

### Welcome

Hi.

## Usage

### Start
```


---

<!-- reference -->

# API reference

## Conventions

Public functions take **at most one positional argument**; everything else is
keyword-only.

```python
from_html(markup, parser="lxml")     # not from_html(markup, "lxml")
```

Tag constructors reach the same place by a different route. Their positional
arguments are variadic children, and Python makes everything after `*children`
keyword-only, so anything you name is an attribute:

```python
Div(H1("Title"), P("Body"), class_="card")
#   \________ children ________/  \_ attrs _/
```

On the generic `Tag`, the element name is positional-**only**, which keeps
every possible attribute name free, including `tag` itself:

```python
Tag("div", tag="value")     # <div tag="value"></div>
Tag(_tag="div")             # TypeError
```

Tests enforce both halves across every element class, so this stays true.

## Items

All item types inherit from `HtmlItem`.

`transform(visitor)` is available on every item. It returns a copied tree,
visiting children before parents, including the root. Return an `HtmlItem`
to keep or replace a node, `None` to remove it, or `Fragment` for siblings.
Replacements are not revisited. Removing the root returns `None`.
Copies preserve subclasses and have independent attribute dictionaries and
child lists; nested attribute values remain shared. Callback-provided
replacements are used as-is. See [transformation semantics](../parsing/#transforming-a-copy).

### `Tag`

An element: a name, children, and attributes.

Tag vs. element

MDN and the HTML spec would call this class an *element*. A tag is
strictly just the `<div>` marker. The name follows BeautifulSoup, whose
node class is also `Tag`, and everyday usage. The `.tag` field holds the
element's tag name, which matches lxml's `Element.tag` exactly.

```python
Tag(name, *children, **attrs)
```

| Field | Meaning |
| --- | --- |
| `tag` | The element name |
| `children` | List of `HtmlItem` |
| `attrs` | Attributes, keys in HTML spelling |
| `type` | Discriminator, always `"tag"` |

**Properties**

`is_void`
:   Whether this element self-closes and forbids children.

`is_raw_text`
:   Whether content is emitted unescaped (`script`, `style`).

`text`
:   All text in the subtree, unescaped.

`classes`
:   Class tokens in rendering order, accepting the same string, iterable, or
mapping values as rendering. Missing or boolean values return an empty list.

**Methods**

`has_class(name)`
:   Test exact class-token membership. Attribute searches still use exact
equality against the whole attribute.

`get_text(separator="", *, strip=False)`
:   Join text nodes with a separator. With `strip=True`, trim each node and
omit empty ones. Separators apply between inline text nodes too; this
does not infer block boundaries or insert breaks for `<br>`. Comments
and trusted `Raw` markup are excluded, as with `.text`.

`find(tag=None, **attrs)`
:   First matching descendant tag, or `None`. `tag` accepts a name or a
predicate receiving a tag. The root is excluded.

`find_all(tag=None, **attrs)`
:   Every matching descendant tag, accepting the same name or predicate.

`iter_find(tag=None, **attrs)`
:   `find_all()` as a lazy iterator; `find()` uses it to stop at the first
hit.

`walk()`
:   Yields this item then every descendant, depth first.

`render()`
:   The markup, as a `SafeString` when Django is installed.

`render_raw_text()`
:   Content of a raw text element. Raises if it contains the element's own
closing tag.

`__call__(*children)`
:   A **copy** with more children appended. Void elements reject children
here too; `None`, `False`, and empty collections still drop out.

`model_validate(obj)` / `model_validate_json(data)`
:   Load a tree, restoring element classes by their `tag`.

`with_attrs(**attrs)`
:   A shallow copy with supplied attributes replaced, using the constructor's
attribute-name normalization. Classes are replaced, not merged. Unspecified
attributes remain. `None` omits an attribute on render; booleans follow the
usual rendering rules, including explicit values for ARIA attributes.
The attribute dictionary and child list are independent; existing child
objects and nested attribute values remain shared. The subclass is preserved.

Searches traverse fragments in depth-first document order but match only tags.
Keyword attributes keep exact-match semantics and filter before predicates.
Predicates should not modify the tree. `find()` stops after the first match.

### `Fragment`

```python
Fragment(*items)
```

A group of siblings with no wrapping element. Children are coerced just as
with `Tag`: text is escaped, collections flatten, and `None`/`False` drop out.
Fragments can contain tags and other fragments, or appear inside a tag.

The fields are `type="fragment"` and `children`. A fragment supports `render`,
`walk`, `find`, `find_all`, `iter_find`, `transform`, `.text`, `get_text`, and calling it to
create a shallow copy with additional children. `walk()` includes fragment
nodes; searches return descendant tags. Copies have independent child lists
but share existing child objects, just like tags.

`Fragment.model_validate()` and `Fragment.model_validate_json()` restore
nested fragments and element subclasses. Fragments also survive JSON round
trips inside a `Tag`. The keyword arguments `children=` and `type=` are
reserved for deserialization; use positional arguments when building.

`Fragment(parse(markup))` makes multiple parsed roots usable with
`as_response()` or as a Django component result. `parse()` and `from_html()`
keep their existing return types. `to_markdown()` accepts fragments too.

### `JsonLd`

`JsonLd(data, **attrs)` is a `Script` holding `data` as JSON-LD, ready to nest
anywhere a tag goes. `data` may be any Pydantic model, a dict, a list, or a
mix; nothing has to inherit from anything here.

```python
Head(Title("Acme"), JsonLd(Organization(name="Acme", url="/")))
```

`None` fields drop out, since a JSON-LD null is not a value. The JSON is
escaped per `JSON_LD_ESCAPES` so no string in it can end the script element
or open an HTML comment, which matters because a `<script>` is raw text.
Keyword arguments become attributes, `type` included.

Models are dumped by alias, since `@context` and `@type` are not Python names
and can only be declared as aliases, and with `None` dropped. To dump on
other terms, call `model_dump()` yourself and hand over the dict.

Parsing or re-validating one gives back a plain `Script`, since a tag name
maps to a single class and `script` is taken. It renders identically, and
`json.loads(tag.text)` reads the data back.

### `JsonScript`

`JsonScript(data, **attrs)` creates a `Script` with
`type="application/json"` for browser code to read with `JSON.parse()`.
It accepts JSON values and nested Pydantic models, using model aliases and
JSON-mode serialization. Unlike `JsonLd`, model fields with `None` are
preserved as `null`. Non-finite numbers are rejected because they are not
valid JSON.

```python
JsonScript({"theme": "dark", "selection": None}, id="page-config")
```

The same script-safe character escaping used by `JsonLd` prevents data
from closing the element. Keyword arguments become attributes, including
an optional override of `type`. Parsing or loading through `Tag` restores
a plain `Script` with identical output.

See the [JavaScript data recipe](../cookbook/#passing-data-to-javascript).

### `Text`

Escaped text. `Text(content="a < b")` renders `a &lt; b`.

### `Raw`

Unescaped markup. `Raw(content="<b>x</b>")` renders as-is.

Danger

Never build a `Raw` from untrusted input.

### `Doctype`

`Doctype()` renders `<!DOCTYPE html>`; `content` overrides what follows
`<!DOCTYPE`, for legacy identifiers. A `>` in the content would end the
declaration early, so rendering refuses it.

### `Comment`

`Comment(content="note")` renders `<!--note-->`. Comment syntax rules are
neutralized on render: `--` becomes `- -`, a leading `>`/`->` and a trailing
`-` are padded with a space. HTML5 would otherwise read the comment as
closed early and parse the remainder as live markup.

## Functions

`parse(html, *, parser=None)`
:   Parse into a list of top-level items. Needs the `parse` extra.

`from_html(html, *, parser=None)`
:   Like `parse()`, but unwraps a single root.

`best_parser()`
:   The best BeautifulSoup backend installed.

`tag_class(tag, *, name=None)`
:   Build and register a `Tag` subclass for one element name.

`normalize_attr(name)`
:   Python attribute spelling to HTML: `class_` to `class`. A trailing
underscore is dropped, so any Python keyword works as `keyword_`, and
remaining underscores become hyphens. Seven attribute names across HTML
and SVG need the underscore; see
[Reserved words](../building/#reserved-words).

`render_json_ld(data)`
:   Serialize a model, dict, or list as JSON that is safe inside a
`<script>`. The escaping is lossless, so `json.loads` returns what went
in. `JsonLd` and `JsonScript` call it for you; see the
[JSON-LD recipe](../cookbook/#json-ld-from-a-pydantic-model).

`as_json(value)`
:   The `json.dumps(..., default=...)` hook that reaches Pydantic models.

`is_collection(value)`
:   Whether a value should be flattened as a group of children.

`marker()`
:   Django's `mark_safe` if installed, otherwise a passthrough.

`warn_element(tag)`
:   Raise `DeprecatedElementWarning` or `ExperimentalElementWarning` for a
retired or unsettled element, else do nothing. Called when markup is
authored, never when it is parsed or deserialized. Warnings de-duplicate
per call site, so a tag in a loop reports once. See
[Deprecated and experimental elements](#deprecated-and-experimental-elements).

### Internals

These are module-level functions rather than exported API: they are absent
from `__all__` and from the type stub, so a type checker rejects importing
them even though the import works at run time. They are listed because they
turn up in tracebacks, not because a caller should need them.

`render_attrs(attrs)` / `render_class(value)` / `render_style(value)`
:   The attribute rendering helpers, called during `render()`. To read or
build class tokens yourself, use the `classes` property and
[`with_attrs()`](#tag) instead.

`iter_children(children)`
:   Coerce arbitrary values into items, applying the drop, flatten, trust,
and escape rules. [`Fragment(...)`](#fragment) applies the same rules and
gives you something you can render.

## Constants

| Name | Contents |
| --- | --- |
| `TAG_CLASSES` | Tag name to class, including ones registered at runtime |
| `BUILTIN_TAGS` | The element names this library ships |
| `DEPRECATED_ELEMENTS` | Elements the standard retired; building one warns |
| `EXPERIMENTAL_ELEMENTS` | Elements not settled across engines |
| `ITEM_CLASSES` | Discriminator to leaf class |
| `VOID_ELEMENTS` | Elements that self-close |
| `RAW_TEXT_ELEMENTS` | `script`, `style` |
| `PRE_ELEMENTS` | `pre`, `textarea` |
| `DOCUMENT_ELEMENTS` | `html`, `head`, `body` |
| `ATTR_NAME_RE` | What a rendered attribute name may look like |
| `JSON_LD_ESCAPES` | Rewrites applied to JSON going inside a `<script>` |
| `PARSERS` | Parser preference order |

## Element classes

Every element in the HTML living standard has a generated class, named after
the tag with a capital letter: `Div`, `P`, `H1`, `Textarea`, `Del`. Names are
capitalized so they never collide with builtins like `input`, `object`, or
`map`.

**138 elements** are generated: the 113 current elements of the
[WHATWG HTML living standard](https://html.spec.whatwg.org/multipage/indices.html#elements-3),
including recent additions like `search` and `selectedcontent`, plus 19
deprecated and 6 experimental ones. The three sets are tracked against
[MDN's browser-compat-data](https://github.com/mdn/browser-compat-data/tree/main/html/elements).
Each class's docstring links to its
[MDN element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element),
the best per-element documentation available, so `help(Div)` points at the
right page. Five elements browser-compat-data tracks have no MDN page yet
(`camera`, `install`, `microphone`, `model`, `usermedia`); their docstrings
carry no link rather than one that 404s.

### Deprecated and experimental elements

Retired elements are still generated, because old documents still contain
them and parsing has to name them something. Writing one by hand raises
`DeprecatedElementWarning`, a `DeprecationWarning` subclass, so it is quiet
in application code and loud where it is actionable -- test suites, the
REPL, and `python -W`:

```python
import warnings
from django_div import DeprecatedElementWarning

warnings.filterwarnings("ignore", category=DeprecatedElementWarning)
```

Experimental elements raise `ExperimentalElementWarning`, which is filtered
out on import, since choosing one is a bet rather than a mistake. Ask for it:

```python
warnings.filterwarnings("default", category=ExperimentalElementWarning)
```

Both warnings fire when markup is authored, never when it is parsed or
deserialized, so the warning always points at a line someone can change and
a legacy document does not flood the log. `DEPRECATED_ELEMENTS` and
`EXPERIMENTAL_ELEMENTS` name the sets, for a codebase that would rather grep
than wait for a warning.

Tests are parametrized over `TAG_CLASSES`, so every element is checked for
rendering, attributes, category behavior, and both round trips.

### All elements

The **Notes** column marks the behavior sets -- `void` elements self-close
and take no children, `raw text` content is never escaped, and `pre` content
keeps its whitespace verbatim -- and the standing of elements that are not
current: `deprecated` and `experimental`.

| Class | Tag | Notes |
| --- | --- | --- |
| `A` | `<a>` |  |
| `Abbr` | `<abbr>` |  |
| `Acronym` | `<acronym>` | deprecated |
| `Address` | `<address>` |  |
| `Area` | `<area>` | void |
| `Article` | `<article>` |  |
| `Aside` | `<aside>` |  |
| `Audio` | `<audio>` |  |
| `B` | `<b>` |  |
| `Base` | `<base>` | void |
| `Bdi` | `<bdi>` |  |
| `Bdo` | `<bdo>` |  |
| `Big` | `<big>` | deprecated |
| `Blockquote` | `<blockquote>` |  |
| `Body` | `<body>` |  |
| `Br` | `<br>` | void |
| `Button` | `<button>` |  |
| `Camera` | `<camera>` | experimental |
| `Canvas` | `<canvas>` |  |
| `Caption` | `<caption>` |  |
| `Center` | `<center>` | deprecated |
| `Cite` | `<cite>` |  |
| `Code` | `<code>` |  |
| `Col` | `<col>` | void |
| `Colgroup` | `<colgroup>` |  |
| `Data` | `<data>` |  |
| `Datalist` | `<datalist>` |  |
| `Dd` | `<dd>` |  |
| `Del` | `<del>` |  |
| `Details` | `<details>` |  |
| `Dfn` | `<dfn>` |  |
| `Dialog` | `<dialog>` |  |
| `Dir` | `<dir>` | deprecated |
| `Div` | `<div>` |  |
| `Dl` | `<dl>` |  |
| `Dt` | `<dt>` |  |
| `Em` | `<em>` |  |
| `Embed` | `<embed>` | void |
| `Fencedframe` | `<fencedframe>` | deprecated |
| `Fieldset` | `<fieldset>` |  |
| `Figcaption` | `<figcaption>` |  |
| `Figure` | `<figure>` |  |
| `Font` | `<font>` | deprecated |
| `Footer` | `<footer>` |  |
| `Form` | `<form>` |  |
| `Frame` | `<frame>` | void, deprecated |
| `Frameset` | `<frameset>` | deprecated |
| `Geolocation` | `<geolocation>` | experimental |
| `H1` | `<h1>` |  |
| `H2` | `<h2>` |  |
| `H3` | `<h3>` |  |
| `H4` | `<h4>` |  |
| `H5` | `<h5>` |  |
| `H6` | `<h6>` |  |
| `Head` | `<head>` |  |
| `Header` | `<header>` |  |
| `Hgroup` | `<hgroup>` |  |
| `Hr` | `<hr>` | void |
| `Html` | `<html>` |  |
| `I` | `<i>` |  |
| `Iframe` | `<iframe>` |  |
| `Img` | `<img>` | void |
| `Input` | `<input>` | void |
| `Ins` | `<ins>` |  |
| `Install` | `<install>` | experimental |
| `Kbd` | `<kbd>` |  |
| `Label` | `<label>` |  |
| `Legend` | `<legend>` |  |
| `Li` | `<li>` |  |
| `Link` | `<link>` | void |
| `Main` | `<main>` |  |
| `Map` | `<map>` |  |
| `Mark` | `<mark>` |  |
| `Marquee` | `<marquee>` | deprecated |
| `Menu` | `<menu>` |  |
| `Meta` | `<meta>` | void |
| `Meter` | `<meter>` |  |
| `Microphone` | `<microphone>` | experimental |
| `Model` | `<model>` | experimental |
| `Nav` | `<nav>` |  |
| `Nobr` | `<nobr>` | deprecated |
| `Noembed` | `<noembed>` | deprecated |
| `Noframes` | `<noframes>` | deprecated |
| `Noscript` | `<noscript>` |  |
| `Object` | `<object>` |  |
| `Ol` | `<ol>` |  |
| `Optgroup` | `<optgroup>` |  |
| `Option` | `<option>` |  |
| `Output` | `<output>` |  |
| `P` | `<p>` |  |
| `Param` | `<param>` | void, deprecated |
| `Picture` | `<picture>` |  |
| `Plaintext` | `<plaintext>` | deprecated |
| `Pre` | `<pre>` | pre |
| `Progress` | `<progress>` |  |
| `Q` | `<q>` |  |
| `Rb` | `<rb>` | deprecated |
| `Rp` | `<rp>` |  |
| `Rt` | `<rt>` |  |
| `Rtc` | `<rtc>` | deprecated |
| `Ruby` | `<ruby>` |  |
| `S` | `<s>` |  |
| `Samp` | `<samp>` |  |
| `Script` | `<script>` | raw text |
| `Search` | `<search>` |  |
| `Section` | `<section>` |  |
| `Select` | `<select>` |  |
| `Selectedcontent` | `<selectedcontent>` |  |
| `Slot` | `<slot>` |  |
| `Small` | `<small>` |  |
| `Source` | `<source>` | void |
| `Span` | `<span>` |  |
| `Strike` | `<strike>` | deprecated |
| `Strong` | `<strong>` |  |
| `Style` | `<style>` | raw text |
| `Sub` | `<sub>` |  |
| `Summary` | `<summary>` |  |
| `Sup` | `<sup>` |  |
| `Table` | `<table>` |  |
| `Tbody` | `<tbody>` |  |
| `Td` | `<td>` |  |
| `Template` | `<template>` |  |
| `Textarea` | `<textarea>` | pre |
| `Tfoot` | `<tfoot>` |  |
| `Th` | `<th>` |  |
| `Thead` | `<thead>` |  |
| `Time` | `<time>` |  |
| `Title` | `<title>` |  |
| `Tr` | `<tr>` |  |
| `Track` | `<track>` | void |
| `Tt` | `<tt>` | deprecated |
| `U` | `<u>` |  |
| `Ul` | `<ul>` |  |
| `Usermedia` | `<usermedia>` | experimental |
| `Var` | `<var>` |  |
| `Video` | `<video>` |  |
| `Wbr` | `<wbr>` | void |
| `Xmp` | `<xmp>` | deprecated |

## `django_div.markdown`

`to_markdown(item)`
:   Render an item or list of items as Markdown. No dependencies.

`from_markdown(text, *, parser=None)`
:   Read Markdown into a tree via markdown-it-py; needs the `markdown` extra.

`INLINE_WRAPPERS` / `HEADING_TAGS` / `CONTAINER_TAGS` / `TRANSPARENT_TAGS` / `DROP_TAGS`
:   The per-tag reference tables driving the renderer; extend them to teach
it new elements.

## `django_div.django`

`DjangoDivTemplates`
:   Template backend whose templates are dotted paths to callables.

`as_response(item, **kwargs)`
:   Render straight into an `HttpResponse`.

`csrf_input(request)`
:   The hidden CSRF field, as a `Raw`.

`render_component(component, *, context)`
:   Call a component with the parts of the context it declares.

`Template` is the adapter `DjangoDivTemplates` hands back so Django has
something with a `render()` on it. Django constructs it; you do not.

Ordinary function components reuse inspected keyword parameter names in a
bounded cache of 256 functions. Callable objects are inspected each time, so
state-dependent signatures and unhashable instances work. Function signatures
should remain stable after first use; replacing a function creates a new
cache entry. Rendered output and request context are never cached.


---

<!-- contributing -->

# Contributing

## Setup

```console
git clone git@github.com:jefftriplett/django-div.git
cd django-div
just bootstrap
just install-hooks
```

`just bootstrap` runs `uv sync`, which installs the package plus the dev
group: pytest, ruff, prek, Django, and both parser backends.

## Commands

| Command | What it does |
| --- | --- |
| `just test` | Run pytest; extra arguments pass through |
| `just lint` | Run every hook over every file |
| `just ruff` | Just ruff, check and format |
| `just docs` | Serve the docs with live reload |
| `just docs-build` | Build the docs into `site/`, plus llms.txt |
| `just example` | Run `examples/example.py` |
| `just stub` | Regenerate `src/django_div/__init__.pyi` |
| `just compat` | Refresh the MDN compat snapshot the tests read |
| `just install-hooks` | Install the prek git hooks |
| `just update-hooks` | Update pinned hook versions |
| `just build` | Build the sdist and the wheel into `dist/` |
| `just lock` | Refresh `uv.lock` |
| `just bump` | Raise the CalVer version and tag it |
| `just bump-dry` | The same, printed rather than applied |
| `just release` | Bump, relock, and push the tag |

```console
just test -k parse -x
```

## Layout

```text
src/django_div/__init__.py   the library
src/django_div/__init__.pyi  generated type stub, see `just stub`
src/django_div/django.py     the Django integration
tests/test_django_div.py     core behavior
tests/test_tags.py           every tag, parametrized
tests/test_attributes.py     every attribute name, and input types
tests/test_django.py         the Django integration
tests/components.py          components the Django tests render
tests/compat.py              the compat snapshot, as sets
tests/data/compat.json       generated MDN snapshot, see `just compat`
examples/example.py          a runnable tour
docs/                        this site
```

## Conventions

**Alphabetical order.** Constants, then functions, then classes. Each group is
sorted, subject to Python needing base classes and helpers defined first.

**One positional argument.** Public functions take at most one positional
argument; everything else is keyword-only, enforced by
`test_public_functions_take_at_most_one_positional_argument`.

Tag constructors land in the same place differently: their positionals are
variadic children, so Python makes every named argument keyword-only, and the
generic `Tag` takes its element name positional-only. `test_tags.py` checks
the constructor shape of every element class.

**Comments explain why.** The what is in the code. Comments are for the
reason a thing is the way it is, usually a Pydantic or HTML constraint that
isn't obvious from reading.

## Tests

Every generated tag is covered by parametrized tests over `TAG_CLASSES`,
which check rendering empty and with attributes and children, category
behavior, and both round trips. The generated set is compared in both
directions against `tests/data/compat.json`, a distilled snapshot of
[mdn/browser-compat-data](https://github.com/mdn/browser-compat-data), so a
missing or invented element fails. `DEPRECATED_ELEMENTS` and
`EXPERIMENTAL_ELEMENTS` are checked against it too, as are the global
attribute and input type lists in `tests/test_attributes.py`.

`just compat` refreshes that snapshot from the published npm package. It is
committed rather than fetched during a test run, so the suite stays offline
and deterministic, and so a status change arrives as a diff someone reads:
BCD itself is 1.3 MB of per-browser version tables that churn with every
Chrome release, and the snapshot is the ~20 KB anyone would actually look at.
A refresh that moves something fails the suite until the library catches up.

Adding an element means adding it to `_TAGS`. If it belongs to a category,
add it to `VOID_ELEMENTS`, `RAW_TEXT_ELEMENTS`, or `PRE_ELEMENTS` as well. The tests
will tell you. Then run `just stub`: the element classes are created at
runtime, which type checkers cannot see, so `src/django_div/__init__.pyi`
declares them all. `tests/test_stub.py` fails if the stub goes stale.

Deprecation warnings are errors:

```toml
filterwarnings = ["error::DeprecationWarning"]
```

So a Pydantic or Django deprecation fails the suite rather than scrolling
past.

## llms.txt

`scripts/gen_llms.py` runs after `zensical build` and writes `llms.txt`,
`llms-full.txt`, and a Markdown twin next to every page. Zensical has no
plugin API yet, so it is a post-build step rather than a plugin.

It reads the **rendered HTML**, not `docs/*.md`. The docs use Zensical syntax
that means nothing outside the renderer (admonitions, grid cards, content
tabs), and a reader of the source would get raw `!!!` markers. Rendering first
turns them into prose.

The conversion itself is the library's own: each page goes through
`from_html()`-style parsing and `django_div.markdown.to_markdown()`, so every
docs build exercises both on real pages. The script only selects the
`<article>`, prunes navigation, permalink anchors, and icon SVGs, and
assembles `llms.txt`.

Page order comes from the `nav` in `zensical.toml`. A page missing from the
nav is appended alphabetically rather than dropped.

## CI

`.github/workflows/test.yml` runs pytest on Python 3.12, 3.13, 3.14, and
3.15, including the free-threaded builds `3.14t` and `3.15t`. The same file
runs lint.

Read the Docs builds and deploys the documentation. `.readthedocs.yaml`
configures it, and it runs the same `zensical build` plus `gen_llms.py` steps
as `just docs-build`.

## Releasing

Versions are CalVer, `YYYY.M.N`: an unpadded month, and a micro that starts
at 1 for each release within that month. `bumpver` owns the number, and its
configuration lives in `[tool.bumpver]`. It writes the version into
`pyproject.toml` and `src/django_div/__init__.py`, which a test compares.

Move the `Unreleased` entries in `CHANGELOG.md` under the new version number
first. Then check what a bump would produce, and run it:

```console
just bump-dry
just release
```

`just release` bumps the version, commits, refreshes `uv.lock`, amends the
lock file into the same commit, re-creates the tag over it, and pushes the
commit with its tag.

The tag is what publishes. `.github/workflows/release.yml` matches a
`YYYY.M.N` tag, runs the tests, builds the sdist and the wheel, and uploads
them to PyPI.

There is no API token. PyPI uses **Trusted Publishing**: the workflow asks
GitHub for a short-lived OIDC token, and PyPI accepts it because the
repository, the workflow file, and the environment match what the project
declares. That is why the job carries `id-token: write` and runs in the
`pypi` environment.