LHTML+ lhtml-site

Use LHTML alone

LHTML is a command and a Python library of its own: you need lhtml-site only to build slides or a whole site. Alone, LHTML converts a text file into an HTML page, or a string into HTML inside your own Python tool.

Needs: Python 3.10 or laterTime: 5 minYou get: an HTML page from a text file

1. Install the lhtml command

pipx install lhtml-markup
lhtml --version

The package is named lhtml-markup; the command and the Python module are named lhtml. In a Python project, install it in its virtual environment instead: python -m pip install lhtml-markup. pipx itself: see Install.

2. A first page

Write notes.l.html:

= Course notes

== Week 1

* **Read** the chapter on __interpolation__
* Run `python demo.py`

then convert it:

lhtml notes.l.html --title "Course notes" -o notes.html

notes.html is a complete page: open it in your browser. Without --title, lhtml writes only the HTML of the content, to put in a page of your own.

  • Several files at once: lhtml pages/*.l.html --title Notes -o site/ writes site/a.html, site/b.html...
  • A mistake gives a warning with its place, and the page is still written: notes.l.html:12:1: warning: div:: is never closed (near 'div::').

3. Your style and your own tags

A stylesheet goes with --css; a tag you use on every page is a macro, declared once in a YAML file given with -m:

# macros.yaml
note:
  class: note
lhtml -m macros.yaml notes.l.html --title "Course notes" --css style.css -o notes.html

note:: ... :: then gives <div class="note"> ... </div>, styled by .note in style.css. More in Your own tags: macros and, for the colors of code blocks, Code.

4. From Python

import lhtml

macros = lhtml.load_macros('macros.yaml')
with open('notes.l.html', encoding='utf-8') as f:
    html = lhtml.run(f.read(), macros=macros)           # the HTML of the content
page = lhtml.wrap(html, title='Course notes', css=['style.css'])   # a complete page

lhtml.run takes a string and returns HTML; it reads no file and writes none. Its options (line_breaks, tags, lexers...) are in the Python API.

5. With a template engine

LHTML leaves {{ ... }} and {% ... %} as they are, so a Jinja2 template can be written in LHTML: convert first, then render.

import jinja2, lhtml

source = '''= {{ title }}
{% for week in weeks %}
== Week {{ loop.index }}: {{ week }}
{% endfor %}'''
template = jinja2.Template(lhtml.run(source))
print(template.render(title='Animation', weeks=['Splines', 'Keyframes']))
# <h1>Animation</h1> <h2>Week 1: Splines</h2> <h2>Week 2: Keyframes</h2>
When to use lhtml-site instead

For slides, a PDF of slides, or a site of several pages with a menu, lhtml-site does the rest: templates, themes, the menu, videos. It includes LHTML. See Get started.

Next: Headings, the first page of the syntax, or every option in the Syntax reference.

Built with lhtml-site, the docs theme. Part of ScholarTools.