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.
- 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.j2est du Markdown etindex.html.j2du 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 :
= 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__
::
::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.
# Sphères rebondissantes
- **Objectif** : un rebond
- sur le sol= Sphères rebondissantes
* *Objectif* : un rebond
** sur le sol= Sphères rebondissantes
* **Objectif** : un rebond
** sur le solVoir [le cours](https://example.org).
<img src="slide-title.jpg" width="240">Voir link:https://example.org[le cours].
image::slide-title.jpg[width=240]Voir link::https://example.org[le cours].
img::slide-title.jpg[width:240px;]<div class="note" style="color:gray;
border-left:3px solid #ccc;
padding-left:10px;">
Enregistrez avant de construire.
</div>// le style : dans une feuille de style
[.note]
--
Enregistrez avant de construire.
--::(.note)[color:gray; border-left:3px solid #ccc; padding-left:10px;]
Enregistrez avant de construire.
::<div style="display:flex; gap:12px;">
<div style="flex:1;">Gauche</div>
<div style="flex:1;">Droite</div>
</div>// pas de colonnes : un tableau sans bordure
[cols="1,1",frame=none,grid=none]
|===
|Gauche
|Droite
|===::[display:flex; gap:12px;]
::[flex:1;] Gauche ::
::[flex:1;] Droite ::
::```python
print("bonjour")
```[source,python]
----
print("bonjour")
----code::[python]
print("bonjour")
code::[-]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
lhtmlet 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 |  |
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.