LHTML — Lightweight HTML
LHTML is a markup language that simplifies HTML authoring with embedded CSS styling. It is designed to be HTML-first: raw HTML passes through untouched, and only a few shorthand symbols (::, *, =, **, __) trigger conversions.
LHTML is used to build static websites and presentation slides, typically combined with Jinja2 templates.
Installation
From PyPI:
pip install lhtml-markup
Or from source:
git clone https://github.com/drohmer/lhtml.git
cd lhtml
pip install .
For development:
pip install -e ".[dev]"
Dependencies (lark, pygments, pyyaml) are installed automatically.
Quick Start
Command Line
lhtml input.l.html # Convert to stdout
lhtml input.l.html -o output.html # Convert to file
lhtml input.l.html -w # Wrap in full HTML document
lhtml input.l.html -b # Render source line breaks as <br>
lhtml a.l.html b.l.html # Several files: a.html, b.html next to sources
lhtml a.l.html b.l.html -o build/ # Several files into a directory
python -m lhtml input.l.html # Alternative invocation
Files are read and written as UTF-8 (a BOM is accepted). Errors and warnings are reported on stderr with the file name, the remaining files are still processed, and the exit code is non-zero if any file failed. An input file is never overwritten (e.g. lhtml page.html without -o). Includes are looked up in the input file's directory first, then in the current directory.
Python API
import lhtml
html = lhtml.run('= Hello World\nSome **bold** text.\n')
html = lhtml.run(text, {
'wrap-auto': True,
'title': 'My Page',
'css': ['style.css'],
'js': ['script.js'],
})
Syntax Reference
Headings
= Main Title
== Subtitle
=== Level 3
Output:
<h1>Main Title</h1>
<h2>Subtitle</h2>
<h3>Level 3</h3>
With classes/IDs:
=(.highlight #intro) Styled Title
<h1 class="highlight" id="intro">Styled Title</h1>
Lists
* First item
* Second item
** Nested item A
** Nested item B
*** Deep nested
* Back to top level
Produces nested <ul><li> structures.
Inline Formatting
This is **bold** text.
This is __italic__ text.
This is `inline code` text.
Output:
This is <strong>bold</strong> text.
This is <em>italic</em> text.
This is <code class="code-inline">inline code</code> text.
Inside inline code, < and > are escaped (so `std::vector<float>` displays correctly), and **, __, $, include::, code:: and ::# are not interpreted. Existing entities such as < are kept. Named tags such as link:: remain active, but a bare :: is C++ (`::glfwInit()`), not a closing tag.
Tag Elements (the :: system)
The core of LHTML. The general syntax is:
tagName::(.classes #id)[cssStyle]{htmlAttributes} content ::
All bracket groups are optional. If tagName is omitted, defaults to div.
Tag names start with a letter and may contain letters, digits, _ and - (useful for custom tags). A tag is only recognized when it is not glued to a preceding word: std::chrono::seconds, obj.link::x or the Python slice a[::2] are left untouched.
A closing :: may be directly followed by punctuation or HTML (**span::[c] x ::**, important ::,). In a run of colons, :: markers are the pairs ending the run: ::::[...] is a closing :: followed by ::[...], and x:::nl is x: followed by ::nl. A :: between two HTML tags (as in pre-highlighted code <span>::</span>) is left untouched.
A tag that is opened but never closed, or a :: without matching opening tag, produces an LHTMLWarning quoting the beginning of the tag.
Div / Span with Styles
div::[color:red; font-size:120%;]
This text is big and red.
::
span::(.highlight)[font-weight:bold;] inline content ::
Output:
<div style="color:red; font-size:120%;">
This text is big and red.
</div>
<span class="highlight" style="font-weight:bold;"> inline content </span>
Anonymous Div (no tag name)
::[padding:10px; background:#eee;]
Content in a styled div.
::
Output:
<div style="padding:10px; background:#eee;">
Content in a styled div.
</div>
Classes, IDs, and Inline Attributes
::(.classA .classB #myId)[margin:10px;]{data-role="main"}
Content
::
Output:
<div class="classA classB" id="myId" style="margin:10px;" data-role="main">
Content
</div>
Self-Closing (inline)
End the content with :: on the same line:
div::[color:blue;] short text ::
Output:
<div style="color:blue;"> short text </div>
Links
The URL of link::, img::, video:: and videoplay:: is never modified (__, **, $ are kept). Parentheses that are part of the URL are kept (Mercury_(planet), fig(1).png), while a group starting with . or # is a class/id group.
link::https://example.com[Click here]
link::page.html(.nav)[Back to home]
Output:
<a href="https://example.com">Click here</a>
<a class="nav" href="page.html">Back to home</a>
Images
img::photo.jpg[width:400px;]
Output:
<img style="width:400px;" src="photo.jpg" alt="photo.jpg">
Videos
video::assets/clip.mp4[width:600px;]
videoplay::assets/clip.mp4[width:600px;]
videoplay adds autoplay loop muted attributes. The parser automatically detects transcoded codec variants (-vp9.webm, -h265.mp4, -h264.mp4) and poster images (-poster.jpg).
Code Blocks
code::[python]
def hello():
print("Hello, world!")
code::[-]
include::file directives inside a code block insert the file as raw code. Syntax highlighting is powered by Pygments. Any language supported by Pygments can be used. An empty language (code::[]) renders plain text; an unknown language renders plain text with a warning.
Spacer
::nl
Output:
<div style="height:1em;"></div>
Verbatim (raw passthrough)
Content inside verbatim blocks is preserved exactly as-is, with no LHTML processing:
verbatim::[]
This = is not a title
**not bold** __not italic__
div::[not a tag]
verbatim::[-]
Line breaks
By default, line breaks of the source have no visual effect (as in HTML). With the option -b / --line-breaks (or line-breaks: true in the YAML front matter, or {'line-breaks': True} in the meta passed to lhtml.run()), each line break of the text is rendered with <br>, blank lines included:
Line 1 Line 1<br>
Line 2 => Line 2<br>
<br>
Other paragraph Other paragraph
Images and videos are inline: images written one per line are stacked (write them on the same line to keep them side by side). Lines that start or end with a block element (headings, lists, div::, block-level HTML tags such as <div>, <p>, <li>, code and verbatim blocks, <script>, display math, ...) are structure: they never get a <br> and blank lines next to them are ignored. The content of code blocks, verbatim blocks, scripts, comments and math is never modified.
Comments
Some text ::# This comment will be removed
A comment starts a line or follows whitespace, so link::#intro[...] (link to an anchor) is not a comment.
File Inclusion
include::header.html
include::components/nav.html
Included files are recursively processed (up to 20 levels); their own YAML front matter is ignored. An included file looks for its own includes first in its own directory, then in directory_include. A circular include raises LHTMLIncludeLoopError.
YAML Front Matter
The front matter must be at the very beginning of the file (--- separators elsewhere are kept as text). Input text is normalized first: a leading BOM is removed and CRLF line endings become LF.
---
title: "My Page"
css: ["style.css", "theme.css"]
js: "app.js"
wrap-auto: true
---
= Page content starts here
Supported metadata keys:
| Key | Type | Description |
|---|---|---|
title |
string | Page title (used in HTML wrapper) |
css |
string or list | CSS files to include |
js |
string or list | JavaScript files to include |
wrap-auto |
boolean | Wrap output in full HTML document |
line-breaks |
boolean | Render source line breaks as <br> |
directory_include |
list | Directories to search for includes |
Plugin System
Custom Tag Handlers
Register handlers for new :: tag types:
from lhtml.pipeline import tag_registry
def handle_alert(element, tag_to_close, current_directory):
"""Open <div class="alert">; the following :: closes it."""
style = element.get('[]', '')
tag_to_close.append('div')
return f'<div class="alert" style="{style}">', True
tag_registry.register('alert', handle_alert)
Then use in LHTML:
alert::[background:yellow; padding:10px;] Warning message ::
A handler receives the parsed element ('[]', '()', '{}', 'text': the
word glued after the brackets) and returns (html, is_real_tag). To wrap the
content that follows, push the HTML tag name on tag_to_close: the next ::
(or ::name[-]) closes it. Returning is_real_tag=False leaves the source
text unchanged.
Custom Code Lexers
Register custom Pygments lexers for syntax highlighting:
from lhtml.pipeline import lexer_registry
from pygments.lexers import PythonLexer
lexer_registry.register('mypython', PythonLexer)
Custom Pipeline
Create an isolated pipeline with its own tag registry:
from lhtml.pipeline import ProcessingPipeline, TagRegistry
registry = TagRegistry()
registry.register('note', my_note_handler)
pipeline = ProcessingPipeline(registry=registry)
html = pipeline.run(text, {'wrap-auto': True})
Configuration Reference
All keys for the meta dict passed to lhtml.run():
{
'wrap-auto': False, # Wrap in HTML document
'line-breaks': False, # Render source line breaks as <br>
'title': 'Webpage', # Document title
'css': [], # CSS files (string or list)
'js': [], # JS files (string or list)
'directory_include': [], # Search paths for include::
'current_directory': '', # Base directory for video codec detection
}
Design Principles
- HTML-first: Raw HTML is never modified. Only LHTML syntax triggers conversions. In particular, the following are never transformed (not even by
include::or::#): HTML tags and their attributes (URLs containing__, quoted values containing>, ...),<script>and<style>blocks (CSS::before, ...), HTML comments, and math ($...$,$$...$$,\(...\),\[...\], so that$x**2$reaches MathJax/KaTeX intact). Text between HTML tags is still processed. - Island grammar: LHTML syntax "islands" float in a sea of opaque content (HTML, Jinja2 templates, LaTeX, etc.) that passes through untouched.
- Minimal: A few symbols (
::,=,*,**,__,`) cover most needs. No complex configuration required. - Composable: LHTML works seamlessly with Jinja2 templates, making it suitable for static site generators.
Project Structure
src/lhtml/
__init__.py # Public API: run(), analyse_tag(), read_yaml()
cli.py # Command-line interface
pipeline.py # ProcessingPipeline, TagRegistry, LexerRegistry
process.py # Core transformation functions
patterns.py # Centralized regex patterns and utilities
tag_parser.py # Lark-based parser for :: bracket syntax
tag_element.lark # Lark grammar definition
export_html.py # HTML generation for tag elements
listing.py # List processing
code.py # Code syntax highlighting (Pygments)
wrap_html.py # HTML document wrapping
errors.py # Structured error types
License
MIT
Metadata
Release files for lhtml-markup 2.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lhtml_markup-2.3.0.tar.gz | 42.5 kB | Without provenance | Details for lhtml_markup-2.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lhtml_markup-2.3.0-py3-none-any.whl | Python 3 | none | any | Details for lhtml_markup-2.3.0-py3-none-any.whl |
Total release size: 75.2 kB
Release files / lhtml_markup-2.3.0.tar.gz
| Download URL | lhtml_markup-2.3.0.tar.gz |
|---|---|
| Size | 42.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ee2b7003c66b83289be1199812c0ef6fe36112261b9db13c9b3fbe9b73615c0d
|
|
BLAKE2b-256 checksum How to use checksums |
bbae84e4a6599e673c84c7c3a8dbc69eb5ddd0e1d4c28b0d09e6e682217c1347
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / lhtml_markup-2.3.0-py3-none-any.whl
| Download URL | lhtml_markup-2.3.0-py3-none-any.whl |
|---|---|
| Size | 32.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
806b9a375f3795bbd400b8b3329ee9a696fbd38d04109da1251ee55d51e99179
|
|
BLAKE2b-256 checksum How to use checksums |
441c8672ccf5aeff9650f323d2f683b04bfa41210e4764ca4a152c35d1b59fce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for lhtml-markup 2.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.