Skip to main content

LHTML — Lightweight HTML

Tests PyPI

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. No input file in the batch is overwritten (including through symbolic or hard links) (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 &lt; 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>

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. The URL may contain Jinja expressions (img::{{ base }}/photo.jpg, link::{{ url_for('page') }}[Home]), which are kept unchanged.

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, including tags spanning multiple lines (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.
  • Styles, classes/IDs and HTML attributes in LHTML tag groups are preserved without inline formatting. Link labels still support formatting.
  • Jinja2 expressions ({{ ... }}), statements ({% ... %}) and comments ({# ... #}) pass through unchanged.
  • 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.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lhtml-markup 2.4.0
File Size Uploaded Provenance Actions
lhtml_markup-2.4.0.tar.gz 46.6 kB Without provenance Details for lhtml_markup-2.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lhtml-markup 2.4.0
File Interpreter ABI Platform Actions
lhtml_markup-2.4.0-py3-none-any.whl Python 3 none any Details for lhtml_markup-2.4.0-py3-none-any.whl

Total release size: 80.7 kB

Release files / lhtml_markup-2.4.0.tar.gz

Download URL lhtml_markup-2.4.0.tar.gz
Size 46.6 kB
Tags Source
SHA-256 checksum
How to use checksums
59b21a5b8a7bd6a4839d10c6af3b242dd8a4d358c025da7fd006e4a020e720c3
BLAKE2b-256 checksum
How to use checksums
9684cad2e6ed902a6dc49c35c24707e166ba54f621a121ab8dbba3718d85e7d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Release files / lhtml_markup-2.4.0-py3-none-any.whl

Download URL lhtml_markup-2.4.0-py3-none-any.whl
Size 34.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0049ab3e6e7977a56c549663df940a2fb025c8964734b78914753d70f2faf0da
BLAKE2b-256 checksum
How to use checksums
fc103652ecc691d1aa0dcc476b6cfd7904963797da792275b191d241d44489ed
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Security for lhtml-markup 2.4.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page