LHTML+ lhtml-site

Thèmes

Les pages disent quoi montrer ; le thème dit comment. Changez la ligne theme: de configure.yaml, reconstruisez, et les mêmes pages prennent une autre forme.

Les quatre thèmes

Une slide du thème slides
slides : des slides dans le navigateur, 1920×1080, les flèches du clavier pour avancer
Une slide telle qu'imprimée dans le PDF
slides-pdf : les mêmes slides en PDF, et une image de chacune
Une page du thème webpage-frame
webpage-frame : des pages web avec un menu, pour un cours
Une page du thème docs
docs : un site de documentation avec recherche, comme celui-ci

Chaque image ouvre le vrai résultat, construit à partir des projets de départ de lhtml-site init par la version actuelle de lhtml-site. De vrais cours : Faits avec LHTML.

Thème Pour Nécessite
slides Des slides dans le navigateur rien de plus
slides-pdf Les mêmes slides, en PDF Playwright et son Chromium (recette)
webpage-frame (par défaut) Des pages web avec un menu de navigation : un cours rien de plus
docs Un site de documentation : recherche, menu par section, « Sur cette page », clair et sombre pour la recherche, un index Pagefind (recette)

Ce qu'apportent les thèmes de slides

Les thèmes de slides fournissent des macros, des balises écrites une fois dans le thème, et des mises en page, qui placent pour vous les blocs d'une slide. Une slide choisit sa mise en page dans son en-tête YAML (front matter), entre deux lignes --- tout en haut du fichier :

---
layout: side
---
= Cinématique directe

* Chaque angle d'articulation est réglé à la main
gap::
* Les rotations sont interpolées

media::
img::assets/fk.jpg
credit:: Image : Wikimedia Commons ::
::
  • Macros : gap:: (un espace), small::, center::, cols:: et col::, box:: (.good, .bad, .warn, .key), credit::, aside::, media::...
  • Mises en page : side (texte à gauche, figures à droite ; side-s et side-l pour une colonne plus étroite ou plus large), stack (figures sous le texte), section (une slide de titre).
  • media:: contient les figures, que la mise en page place et dimensionne : aucune position ni largeur à écrire.

Les slides de départ de lhtml-site init choisissent leur mise en page autrement, avec {% set layout = 'side' %} en haut du fichier ; les deux fonctionnent.

Après une construction, .structure/design.md liste toutes les macros et mises en page du thème.

Changer l'apparence (sans écrire de thème)

Ce que vous pouvez changer dépend du thème :

Réglage dans configure.yaml slides, slides-pdf webpage-frame docs
macros de design: oui, avec leur CSS la balise seulement : son css n'est pas chargé la balise seulement : son css n'est pas chargé
tokens de design: (tailles, couleurs) oui sans effet sans effet
keywords: cssAbs:, votre feuille de style oui oui non : utilisez docs: css:
keywords: docs: css:, votre feuille de style non non oui

Les macros sont du LHTML : elles fonctionnent dans les pages .html.j2, pas dans les pages Markdown (.md.j2). Dans webpage-frame et docs, donnez son style à la classe d'une macro dans votre propre feuille de style.

Slides : tokens et macros. Les thèmes de slides lisent leurs tailles et leurs couleurs dans des tokens nommés, et vous pouvez ajouter vos propres macros. Dans configure.yaml (une partie de ces lignes y est déjà, derrière un #) :

design:
  tokens:
    font: {small: 80%}          # le texte de small:: un peu plus petit
    space: {m: 30px}            # gap:: un peu plus haut
    color: {muted: '#555'}      # le texte de muted:: plus foncé
  macros:
    note:                       # une nouvelle macro : note:: texte ::
      class: note
      css: '.note { color: #c0392b; font-style: italic; }'
      doc: 'Une remarque en rouge : note:: texte ::'

Ils s'ajoutent à ceux du thème ; après une construction, .structure/design.md les liste tous.

Slides et webpage-frame : votre feuille de style. Écrivez src/assets/my.css et indiquez-la, depuis la racine du site :

keywords:
  cssAbs: [assets/my.css]

Elle est chargée après les feuilles de style du thème : ses règles l'emportent.

docs : votre feuille de style. Chaque couleur et chaque taille du thème est une variable CSS (--accent, --bg, --text...) : quelques lignes suffisent à changer son apparence. C'est ce que fait ce site. Par exemple, pour changer la couleur d'accent en mode clair comme en mode sombre, écrivez src/assets/my.css :

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

et ajoutez à configure.yaml :

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

Les autres réglages du thème (nom, logo, liens) sont dans le thème docs (en anglais).

Écrire votre propre thème

Quand les réglages ci-dessus ne suffisent pas, partez d'une copie : copiez un thème de lhtml-site dans votre projet (ils sont dans le répertoire themes/ du générateur ; lhtml-site doctor affiche où se trouve le générateur), modifiez ses fichiers, et faites pointer theme: vers ce répertoire.

Ou écrivez-en un de zéro. Un thème est un répertoire avec un theme.yaml et un gabarit Jinja :

my-theme/
  theme.yaml
  template/base.html
  css/my.css
# my-theme/theme.yaml
template: 'theme/template/base.html'   # le gabarit qui enveloppe chaque page
content_block: 'content'               # le bloc que la page remplit
<!-- 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>

et dans configure.yaml : theme: 'my-theme/'. Le thème est copié dans le site sous le nom theme/. Ce qu'un thème peut déclarer (un menu, la taille d'une page, une page 404) et les variables que reçoit un gabarit sont dans la référence de lhtml-site ; la page du thème docs décrit un thème complet, fichier par fichier (en anglais).

Construit avec lhtml-site, thème docs. Fait partie de ScholarTools.