LHTML+ lhtml-site

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.

In short
  • 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.j2 is Markdown and index.html.j2 is 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 :::

The same page in LHTML
LHTML
= 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__
::
::
Result
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.

Headings, lists and bold
Markdown
# Bouncing spheres

- **Goal**: one bounce
  - on the ground
AsciiDoc
= Bouncing spheres

* *Goal*: one bounce
** on the ground
LHTML
= Bouncing spheres
* **Goal**: one bounce
** on the ground
Result
A link, and an image of a given size
Markdown
See [the course](https://example.org).

<img src="slide-title.jpg" width="240">
AsciiDoc
See link:https://example.org[the course].

image::slide-title.jpg[width=240]
LHTML
See link::https://example.org[the course].
img::slide-title.jpg[width:240px;]
Result
A block with a class and a style
Markdown
<div class="note" style="color:gray;
  border-left:3px solid #ccc;
  padding-left:10px;">

Save before you build.

</div>
AsciiDoc
// the style: in a stylesheet
[.note]
--
Save before you build.
--
LHTML
::(.note)[color:gray; border-left:3px solid #ccc; padding-left:10px;]
Save before you build.
::
Result
Two columns
Markdown
<div style="display:flex; gap:12px;">
<div style="flex:1;">Left</div>
<div style="flex:1;">Right</div>
</div>
AsciiDoc
// no columns: a table without borders
[cols="1,1",frame=none,grid=none]
|===
|Left
|Right
|===
LHTML
::[display:flex; gap:12px;]
::[flex:1;] Left ::
::[flex:1;] Right ::
::
Result
A code block
Markdown
```python
print("hello")
```
AsciiDoc
[source,python]
----
print("hello")
----
LHTML
code::[python]
print("hello")
code::[-]
Result

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 lhtml and 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 ![alt](photo.jpg) 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.

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