trendels.name
Simple HTML Generation https://minihtml.trendels.name/
1.. minihtml documentation master file, created by
2 sphinx-quickstart on Sun Feb 23 13:23:21 2025.
3 You can adapt this file completely to your liking, but it should at least
4 contain the root `toctree` directive.
5
6minihtml
7========
8
9``minihtml`` is a library to generate HTML documents from Python. It aims to
10provide an API that allows you to define the structure of an HTML document in a
11succinct and natural way.
12
13By building up nested HTML elements using context managers, you can combine
14HTML generation with control flow statements in a way that is easy to read and
15does not obscure the structure of the resulting HTML document.
16
17For example, this code:
18
19.. literalinclude:: ../../examples/hello_world.py
20 :language: python
21
22produces this HTML:
23
24.. literalinclude:: ../../examples/hello_world.html
25 :language: html
26
27The short example above already shows a few key features of the API:
28
29- **declarative API**: Using the declarative style, you can use regular ``for``
30 loops and other control flow statements to build up nested elements:
31
32 >>> from minihtml.tags import ul, li
33 >>> with ul as ingredients:
34 ... for item in ("bacon", "lettuce", "tomato"):
35 ... li(item)
36 <...>
37 >>> print(ingredients)
38 <ul>
39 <li>bacon</li>
40 <li>lettuce</li>
41 <li>tomato</li>
42 </ul>
43
44 You can also use a list comprehension of course, but this tends to only work
45 for very simple examples. As soon as you start nesting loops or have inline
46 conditionals, readability suffers.
47
48 >>> ingredients = ul(*[li(item) for item in ("bacon", "lettuce", "tomato")])
49 >>> print(ingredients)
50 <ul>
51 <li>bacon</li>
52 <li>lettuce</li>
53 <li>tomato</li>
54 </ul>
55
56 .. workaround for broken highlighting in vim*
57
58- **fluent API**: Operations on elements can be chained to write code that is
59 close to the generated HTML:
60
61 >>> from minihtml.tags import a
62 >>> link = a(href="http://example.com/")("My Website")
63 >>> print(link)
64 <a href="http://example.com/">My Website</a>
65
66- **shortcuts**: There are convenient shortcuts to set the common HTML
67 attributes `id` and `class`:
68
69 >>> from minihtml.tags import div
70 >>> content = div["#content text-xl font-bold"]
71 >>> print(content)
72 <div id="content" class="text-xl font-bold"></div>
73
74- **pretty printing**: All HTML output is pretty-printed (indented) for easier
75 debugging.
76
77Some additional features:
78
79- A flexible :ref:`component system <components>` with optional :ref:`tracking of JS and CSS dependencies <collecting>`.
80
81- Helpers for :ref:`creating re-useable template with layouts <templates>`.
82
83- Comes with type annotations for the entire API (for use with type checkes
84 such as `mypy <https://mypy-lang.org/>`_ or `pyright
85 <https://microsoft.github.io/pyright>`_).
86
87Continue reading at :ref:`basics` to learn more.
88
89.. toctree::
90 :maxdepth: 2
91 :hidden:
92
93 basics
94 components
95 templates
96 api
97 tags
98
99.. toctree::
100 :hidden:
101 :caption: Meta
102
103 PyPI <https://pypi.org/project/minihtml/>
104 GitHub <https://github.com/trendels/minihtml/>
105 Changelog <https://github.com/trendels/minihtml/blob/main/Changelog.md>