LHTML or Markdown?
Markdown is the best-known way to write HTML as plain text. LHTML makes a different choice: it starts from HTML. Everything you write is HTML, and only a few symbols are read and converted; all of HTML, CSS and JavaScript stays at hand.
- Markdown is made for prose: it hides HTML. LHTML is made for layout: it keeps HTML, and shortens what you write most often, up to boxes and columns with a class or a style.
- For slides and course pages full of styled blocks, LHTML is shorter; for an article or a README, Markdown is simpler and read everywhere.
- Coming from Markdown?
**bold**,*lists and`code`are the same; headings start with=instead of#, italic is__word__. - You do not have to pick one for good: in lhtml-site,
index.md.j2is Markdown andindex.html.j2is LHTML, page by page.
When to choose which
Markdown fits best:
- Mostly prose: an article, notes, a long explanation.
- A text read elsewhere too: a README on GitHub, a wiki, a text sent to a colleague.
- Few or no styled blocks.
LHTML fits best:
- Slides: every slide is a layout, with columns, boxes and images placed on the page.
- Course pages with many styled blocks: exercises, remarks, solutions, figures.
- Authors who know some HTML, or want to learn it: LHTML never hides it, it only shortens it.
You can stop here. The rest of this page compares the two in detail, with AsciiDoc, for the curious.
In detail
The same comparison, step by step: the idea, one page written in both, then the symbols side by side.
The difference
Markdown is made for prose: it hides HTML, and you go back to raw HTML as soon as you need a layout. LHTML is made for layout: it keeps HTML, and shortens what you write most often, from headings and lists to blocks with a class or a style.
Markdown describes content; HTML is its way out, for the rare cases, and some places strip its
styles: on GitHub, style and class are removed and <style> is shown as text. In your own
site, Markdown can reach the same result as LHTML, but by writing full HTML. Some extensions of
Markdown narrow the gap ({: .note}, the ::: blocks of Pandoc), each in its own tool.
LHTML is built for presentation: a block, a span or an image takes a class, a style and attributes in one line; a heading or a link takes a class and an id. These classes link the page to your stylesheet.
The same page, in both
A heading, then two columns: a list on the left, a remark in gray on the right. In Markdown, the columns, the style and the gray remark have no syntax of their own, so they are raw HTML. Markdown is read again inside only with blank lines around it:
# Bouncing spheres <div style="display:flex; gap:12px;"> <div style="flex:1;"> - **Goal**: the collision with the ground - limited to one bounce </div> <div style="flex:1; color:gray; border-left:3px solid #ccc; padding-left:10px;"> *Hint: start with one sphere* </div> </div>
In LHTML, each block is one line, closed by a bare :::
= Bouncing spheres
::[display:flex; gap:12px;]
::[flex:1;]
* **Goal**: the collision with the ground
** limited to one bounce
::
::[flex:1; color:gray; border-left:3px solid #ccc; padding-left:10px;]
__Hint: start with one sphere__
::
::HTML produced
<h1>Bouncing spheres</h1>
<div style="display:flex; gap:12px;">
<div style="flex:1;">
<ul>
<li>
<strong>Goal</strong>: the collision with the ground
<ul>
<li>
limited to one bounce
</li>
</ul>
</li>
</ul>
</div>
<div style="flex:1; color:gray; border-left:3px solid #ccc; padding-left:10px;">
<em>Hint: start with one sphere</em>
</div>
</div>With a macro, the gray remark becomes
note:: ... :: on every page, and its style lives in one place.
Side by side
The same things written in Markdown, in AsciiDoc and in LHTML, with the result. The LHTML source is converted each time this site is built; the others produce the same result.
# Bouncing spheres
- **Goal**: one bounce
- on the ground= Bouncing spheres
* *Goal*: one bounce
** on the ground= Bouncing spheres
* **Goal**: one bounce
** on the groundSee [the course](https://example.org).
<img src="slide-title.jpg" width="240">See link:https://example.org[the course].
image::slide-title.jpg[width=240]See link::https://example.org[the course].
img::slide-title.jpg[width:240px;]<div class="note" style="color:gray;
border-left:3px solid #ccc;
padding-left:10px;">
Save before you build.
</div>// the style: in a stylesheet
[.note]
--
Save before you build.
--::(.note)[color:gray; border-left:3px solid #ccc; padding-left:10px;]
Save before you build.
::<div style="display:flex; gap:12px;">
<div style="flex:1;">Left</div>
<div style="flex:1;">Right</div>
</div>// no columns: a table without borders
[cols="1,1",frame=none,grid=none]
|===
|Left
|Right
|===::[display:flex; gap:12px;]
::[flex:1;] Left ::
::[flex:1;] Right ::
::```python
print("hello")
```[source,python]
----
print("hello")
----code::[python]
print("hello")
code::[-]And beyond the symbols:
- Your own tags: not in Markdown; in LHTML, macros (
note::,cols::...) declared once. - Where it is read: Markdown everywhere (GitHub, editors, Pandoc); AsciiDoc with Asciidoctor,
and on GitHub; LHTML with
lhtmland lhtml-site.
The symbols, side by side
For those who come from Markdown or AsciiDoc: what each one writes, and its LHTML equivalent.
| Markdown | AsciiDoc | LHTML | |
|---|---|---|---|
| Heading | # Heading |
= Heading |
= Heading |
| Section | ## Section |
== Section |
== Section |
| List item | - item |
* item |
* item |
| Nested item | - item (indented) |
** item |
** item |
| Numbered list | 1. item |
. item |
<ol>, in HTML |
| Bold | **bold** |
*bold* |
**bold** |
| Italic | *italic* |
_italic_ |
__italic__ |
| Inline code | `code` |
`code` |
`code` |
| Link | [text](https://...) |
link:https://...[text] |
link::https://...[text] |
| Image |  |
image::photo.jpg[] |
img::photo.jpg |
| Image size | <img width="300"> |
image::photo.jpg[width=300] |
img::photo.jpg[width:300px;] |
| Block with a class | <div class="note">, raw HTML |
[.note] and a delimited block |
::(.note) ... :: |
| Class and id | <div class="note" id="tip">, raw HTML |
[#tip.note] above a block |
::(.note #tip), also on headings, links, images |
| Style in place | style="...", raw HTML |
none: a stylesheet | ::[color:gray;] ... :: |
| Code block | ```python ... ``` |
[source,python], ---- ... ---- |
code::[python] ... code::[-] |
| Paragraph | a blank line | a blank line | <p>, as in HTML (lhtml -b: line breaks as <br>) |
| Comment | <!-- ... --> |
// comment |
<!-- ... --> |
| Raw HTML | allowed, with blank lines around | a passthrough block ++++ |
everywhere |
And AsciiDoc?
LHTML borrows several of its notations from AsciiDoc, a markup made for
books and technical documentation: the headings, the nested lists, link: and image:: with their
attributes in brackets (see the comparison above).
The two part ways on HTML. AsciiDoc, like Markdown, hides it: its blocks have roles (classes) but
no style written in place, and raw HTML needs a passthrough block (++++). LHTML keeps HTML
everywhere and writes a style on any of its blocks, spans and images. AsciiDoc aims at books, PDF
and EPUB, with Asciidoctor (Ruby); LHTML aims at HTML pages and slides, in a small Python package.
Both in one site
In lhtml-site, the extension of each page decides: index.html.j2 is LHTML, index.md.j2 is
Markdown. Both go through Jinja first, so both can use the same variables and templates. This site
does just that: its prose pages, like this one, are Markdown, and its examples are LHTML.
Next: learn LHTML, one short page per construct.