LHTML+ lhtml-site

Themes

The pages say what to show; the theme says how. Change the theme: line in configure.yaml, rebuild, and the same pages take another form.

The four themes

A slide of the slides theme
slides: slides in the browser, 1920×1080, the arrow keys to move
A slide as printed in the PDF
slides-pdf: the same slides as a PDF, and an image of each
A page of the webpage-frame theme
webpage-frame: web pages with a menu, for a course
A page of the docs theme
docs: a documentation site with search, like this one

Each picture opens the real result, built from the starters of lhtml-site init by the current lhtml-site. Real courses: Made with LHTML.

Theme For Needs
slides Slides in the browser nothing more
slides-pdf The same slides, as a PDF Playwright and its Chromium (recipe)
webpage-frame (default) Web pages with a navigation menu: a course nothing more
docs A documentation site: search, menu by section, "On this page", light and dark for the search box, a Pagefind index (recipe)

What the slide themes add

The slide themes come with macros, tags written once in the theme, and layouts, which place the blocks of a slide for you. A slide chooses its layout in its front matter, the YAML between --- lines at its very top:

---
layout: side
---
= Forward kinematics

* Each joint angle is set by hand
gap::
* Rotations are interpolated

media::
img::assets/fk.jpg
credit:: Image: Wikimedia Commons ::
::
  • Macros: gap:: (a space), small::, center::, cols:: and col::, box:: (.good, .bad, .warn, .key), credit::, aside::, media::...
  • Layouts: side (text left, figures right; side-s and side-l for a narrower or wider column), stack (figures below the text), section (a title slide).
  • media:: holds the figures that the layout places and sizes: no position or width to write.

The starter slides of lhtml-site init choose their layout another way, with {% set layout = 'side' %} at the top of the file; both work.

After a build, .structure/design.md lists every macro and layout of the theme.

Change the look (no theme to write)

What you can change depends on the theme:

Setting in configure.yaml slides, slides-pdf webpage-frame docs
design: macros yes, with their CSS the tag only: its css is not loaded the tag only: its css is not loaded
design: tokens (sizes, colors) yes no effect no effect
keywords: cssAbs: your stylesheet yes yes no: use docs: css:
keywords: docs: css: your stylesheet no no yes

Macros are LHTML: they work in .html.j2 pages, not in Markdown pages (.md.j2). In webpage-frame and docs, give the class of a macro its style in your own stylesheet.

Slides: tokens and macros. The slide themes read their sizes and colors from named tokens, and you can add macros of your own. In configure.yaml (a part of these lines is already there, behind a #):

design:
  tokens:
    font: {small: 80%}          # small:: text a little smaller
    space: {m: 30px}            # gap:: a little taller
    color: {muted: '#555'}      # muted:: text darker
  macros:
    note:                       # a new macro: note:: text ::
      class: note
      css: '.note { color: #c0392b; font-style: italic; }'
      doc: 'A remark in red: note:: text ::'

They are added to those of the theme; after a build, .structure/design.md lists all of them.

Slides and webpage-frame: your stylesheet. Write src/assets/my.css and name it, from the root of the site:

keywords:
  cssAbs: [assets/my.css]

It is loaded after the theme's stylesheets, so its rules win.

docs: your stylesheet. Every color and size of the theme is a CSS variable (--accent, --bg, --text...), so a few lines change its look; this site does just that. For example, to change the accent color in light and dark modes, write src/assets/my.css:

:root { --accent: #8a2be2; }
:root[data-theme="dark"] { --accent: #b48cff; }

and add to configure.yaml:

keywords:
  docs:
    css: [assets/my.css]

The theme's other settings (name, logo, links) are in the docs theme.

Write your own theme

When the settings above are not enough, start from a copy: copy a theme of lhtml-site into your project (they are in the directory themes/ of the generator; lhtml-site doctor prints where the generator is), change its files, and point theme: at that directory.

Or write one from scratch. A theme is a directory with a theme.yaml and a Jinja template:

my-theme/
  theme.yaml
  template/base.html
  css/my.css
# my-theme/theme.yaml
template: 'theme/template/base.html'   # the template that wraps each page
content_block: 'content'               # the block the page fills
<!-- my-theme/template/base.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>{{ page.title }}</title>
  <link rel="stylesheet" href="{{ pathToRoot }}theme/css/my.css">
</head>
<body>
  <main>{% block content %}{% endblock %}</main>
</body>
</html>

and in configure.yaml: theme: 'my-theme/'. The theme is copied into the site as theme/. What a theme can declare (a menu, the size of a page, a 404 page) and the variables a template receives are in the lhtml-site reference; the docs theme page describes a complete theme, file by file.

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