LHTML+ lhtml-site

LHTML ou Markdown ?

Markdown est la façon la plus connue d'écrire du HTML en texte brut. LHTML fait un autre choix : il part du HTML. Tout ce que vous écrivez est du HTML, et seuls quelques symboles sont lus et convertis ; tout ce que permettent HTML, CSS et JavaScript reste à portée de main.

En bref
  • Markdown est fait pour la prose : il cache le HTML. LHTML est fait pour la mise en page : il garde le HTML, et raccourcit ce que l'on écrit le plus souvent, jusqu'aux encadrés et aux colonnes avec une classe ou un style.
  • Pour des slides et des pages de cours pleines de blocs stylés, LHTML est plus court ; pour un article ou un README, Markdown est plus simple et lu partout.
  • Vous venez de Markdown ? **gras**, les listes en * et `code` sont identiques ; les titres commencent par = au lieu de #, l'italique s'écrit __mot__.
  • Vous n'avez pas à choisir une fois pour toutes : dans lhtml-site, index.md.j2 est du Markdown et index.html.j2 du LHTML, page par page.

Quand choisir l'un ou l'autre

Markdown convient le mieux pour :

  • Surtout de la prose : un article, des notes, une longue explication.
  • Un texte lu ailleurs aussi : un README sur GitHub, un wiki, un texte envoyé à un collègue.
  • Peu ou pas de blocs stylés.

LHTML convient le mieux pour :

  • Des slides : chaque slide est une mise en page, avec des colonnes, des encadrés et des images placées.
  • Des pages de cours avec beaucoup de blocs stylés : exercices, remarques, solutions, figures.
  • Les auteurs qui connaissent un peu le HTML, ou veulent l'apprendre : LHTML ne le cache jamais, il le raccourcit seulement.

Vous pouvez vous arrêter ici. La suite compare les deux en détail, avec AsciiDoc, pour les curieux.

En détail

La même comparaison, pas à pas : l'idée, une page écrite dans les deux, puis les symboles côte à côte.

La différence

Markdown est fait pour la prose : il cache le HTML, et l'on revient au HTML brut dès qu'il faut une mise en page. LHTML est fait pour la mise en page : il garde le HTML, et raccourcit ce que l'on écrit le plus souvent, des titres et listes jusqu'aux blocs avec une classe ou un style.

Markdown décrit le contenu ; le HTML y est une porte de sortie, pour les cas rares, et certains endroits en retirent les styles : sur GitHub, style et class sont supprimés et <style> est affiché comme du texte. Dans votre propre site, Markdown peut obtenir le même résultat que LHTML, mais en écrivant du HTML complet. Certaines extensions de Markdown réduisent l'écart ({: .note}, les blocs ::: de Pandoc), chacune dans son outil.

LHTML est conçu pour la mise en forme : un bloc, un span ou une image prend une classe, un style et des attributs en une ligne ; un titre ou un lien, une classe et un id. Ces classes relient la page à votre feuille de style.

La même page, dans les deux

Un titre, puis deux colonnes : une liste à gauche, une remarque en gris à droite. En Markdown, les colonnes, le style et la remarque grise n'ont pas de syntaxe propre : ils s'écrivent en HTML brut. Le Markdown n'est lu à l'intérieur qu'entouré de lignes vides :

# Sphères rebondissantes

<div style="display:flex; gap:12px;">
<div style="flex:1;">

- **Objectif** : la collision avec le sol
  - limitée à un seul rebond

</div>
<div style="flex:1; color:gray; border-left:3px solid #ccc; padding-left:10px;">

*Indice : commencer par une seule sphère*

</div>
</div>

En LHTML, chaque bloc tient en une ligne, fermée par un :: seul :

La même page en LHTML
LHTML
= Sphères rebondissantes

::[display:flex; gap:12px;]
::[flex:1;]
* **Objectif** : la collision avec le sol
** limitée à un seul rebond
::
::[flex:1; color:gray; border-left:3px solid #ccc; padding-left:10px;]
__Indice : commencer par une seule sphère__
::
::
Résultat
HTML produit
<h1>Sphères rebondissantes</h1>


<div style="display:flex; gap:12px;">
<div style="flex:1;">
<ul>
<li>
<strong>Objectif</strong> : la collision avec le sol
<ul>
<li>
limitée à un seul rebond
</li>
</ul>
</li>
</ul>
</div>
<div style="flex:1; color:gray; border-left:3px solid #ccc; padding-left:10px;">
<em>Indice : commencer par une seule sphère</em>
</div>
</div>

Avec une macro, la remarque grise devient note:: ... :: sur chaque page, et son style est défini à un seul endroit.

Côte à côte

Les mêmes choses écrites en Markdown, en AsciiDoc et en LHTML, avec leur résultat. La source LHTML est convertie à chaque construction de ce site ; les autres produisent le même résultat.

Titres, listes et gras
Markdown
# Sphères rebondissantes

- **Objectif** : un rebond
  - sur le sol
AsciiDoc
= Sphères rebondissantes

* *Objectif* : un rebond
** sur le sol
LHTML
= Sphères rebondissantes
* **Objectif** : un rebond
** sur le sol
Résultat
Un lien, et une image d'une taille donnée
Markdown
Voir [le cours](https://example.org).

<img src="slide-title.jpg" width="240">
AsciiDoc
Voir link:https://example.org[le cours].

image::slide-title.jpg[width=240]
LHTML
Voir link::https://example.org[le cours].
img::slide-title.jpg[width:240px;]
Résultat
Un bloc avec une classe et un style
Markdown
<div class="note" style="color:gray;
  border-left:3px solid #ccc;
  padding-left:10px;">

Enregistrez avant de construire.

</div>
AsciiDoc
// le style : dans une feuille de style
[.note]
--
Enregistrez avant de construire.
--
LHTML
::(.note)[color:gray; border-left:3px solid #ccc; padding-left:10px;]
Enregistrez avant de construire.
::
Résultat
Deux colonnes
Markdown
<div style="display:flex; gap:12px;">
<div style="flex:1;">Gauche</div>
<div style="flex:1;">Droite</div>
</div>
AsciiDoc
// pas de colonnes : un tableau sans bordure
[cols="1,1",frame=none,grid=none]
|===
|Gauche
|Droite
|===
LHTML
::[display:flex; gap:12px;]
::[flex:1;] Gauche ::
::[flex:1;] Droite ::
::
Résultat
Un bloc de code
Markdown
```python
print("bonjour")
```
AsciiDoc
[source,python]
----
print("bonjour")
----
LHTML
code::[python]
print("bonjour")
code::[-]
Résultat

Et au-delà des symboles :

  • Vos propres balises : absentes de Markdown ; en LHTML, les macros (note::, cols::...) déclarées une seule fois.
  • Où il est lu : Markdown partout (GitHub, éditeurs, Pandoc) ; AsciiDoc avec Asciidoctor, et sur GitHub ; LHTML avec lhtml et lhtml-site.

Les symboles, côte à côte

Pour ceux qui viennent de Markdown ou d'AsciiDoc : ce que chacun écrit, et son équivalent en LHTML.

Markdown AsciiDoc LHTML
Titre # Titre = Titre = Titre
Section ## Section == Section == Section
Élément de liste - item * item * item
Élément imbriqué - item (indenté) ** item ** item
Liste numérotée 1. item . item <ol>, en HTML
Gras **gras** *gras* **gras**
Italique *italique* _italique_ __italique__
Code en ligne `code` `code` `code`
Lien [texte](https://...) link:https://...[texte] link::https://...[texte]
Image ![alt](photo.jpg) image::photo.jpg[] img::photo.jpg
Taille d'image <img width="300"> image::photo.jpg[width=300] img::photo.jpg[width:300px;]
Bloc avec une classe <div class="note">, HTML brut [.note] et un bloc délimité ::(.note) ... ::
Classe et id <div class="note" id="tip">, HTML brut [#tip.note] au-dessus d'un bloc ::(.note #tip), aussi sur les titres, liens, images
Style sur place style="...", HTML brut aucun : une feuille de style ::[color:gray;] ... ::
Bloc de code ```python ... ``` [source,python], ---- ... ---- code::[python] ... code::[-]
Paragraphe une ligne vide une ligne vide <p>, comme en HTML (lhtml -b : sauts de ligne en <br>)
Commentaire <!-- ... --> // commentaire <!-- ... -->
HTML brut permis, entouré de lignes vides un bloc de passage ++++ partout

Et AsciiDoc ?

LHTML emprunte plusieurs de ses notations à AsciiDoc, un balisage conçu pour les livres et la documentation technique : les titres, les listes imbriquées, link: et image:: avec leurs attributs entre crochets (voir la comparaison ci-dessus).

Les deux se séparent sur le HTML. AsciiDoc, comme Markdown, le cache : ses blocs ont des rôles (des classes) mais pas de style écrit sur place, et le HTML brut demande un bloc de passage (++++). LHTML garde le HTML partout et écrit un style sur n'importe lequel de ses blocs, spans et images. AsciiDoc vise les livres, le PDF et l'EPUB, avec Asciidoctor (Ruby) ; LHTML vise les pages HTML et les slides, dans un petit paquet Python.

Les deux dans un même site

Dans lhtml-site, l'extension de chaque page décide : index.html.j2 est du LHTML, index.md.j2 du Markdown. Les deux passent d'abord par Jinja, et peuvent donc utiliser les mêmes variables et les mêmes gabarits. Ce site fait exactement cela : ses pages de prose, comme celle-ci, sont en Markdown, et ses exemples en LHTML.

Suite : apprendre LHTML, une courte page par construction.

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