Markdown
Markdown is the format alternative to HTML that can be used for pages. LuaWebGen specifically uses the GitHub Flavored Markup (GFM) dialect.
Markdown syntax can be divided into two main types of elements: block elements and span elements. Block elements include bigger things like paragraphs and lists, while span elements include parts of text like bold text and links.
Block Elements
Headings
There are two ways to make headings.
The first way is to prefix a line with 1-6 # where more # means higher level (like <h1> through <h6> in HTML).
# Level 1 Heading
### Level 3 Heading
###### Level 6 Heading
<h1 id="level-1-heading">Level 1 Heading</h1>
<h3 id="level-3-heading">Level 3 Heading</h3>
<h6 id="level-6-heading">Level 6 Heading</h6>
A heading may be "closed" with one or more # at the end of the line, but this is purely cosmetic and doesn't affect the resulting HTML.
## Level 2 Heading ##
#### Level 4 Heading ############
<h2 id="level-2-heading">Level 2 Heading</h2>
<h4 id="level-4-heading">Level 4 Heading</h4>
The second way is to underline a line with = (equal signs) for a level 1 heading or - (hyphens) for a level 2 heading.
Level 1 Heading
==============
Level 2 Heading
--------------------------
<h1 id="level-1-heading">Level 1 Heading</h1>
<h2 id="level-2-heading">Level 2 Heading</h2>
Lists
Lines starting with - (hyphens), + (pluses) or * (asterisks) become items in a bullet list.
- Apple
- Banana
* Dog
* Cat
<ul>
<li>Apple</li>
<li>Banana</li>
</ul>
<ul>
<li>Dog</li>
<li>Cat</li>
</ul>
To make an ordered list put a number followed by . or ) at the start of the line.
1. Car
2. Plane
5) Numbering is automatic,
356) but you can start a list
11) from a number other than 1.
<ol>
<li>Car</li>
<li>Plane</li>
</ol>
<ol start="5">
<li>Numbering is automatic,</li>
<li>but you can start a list</li>
<li>from a number other than 1.</li>
</ol>
A list item may be split over multiple lines, even with empty lines in-between. Note that the exact indentation matters a lot!
- Item 1
Continuation of item 1.
> Also, let's have a block quote!
- Item 2
Continuation of item 2.
Separate paragraph here.
<ul>
<li>
<p>Item 1</p>
<p>Continuation of item 1.</p>
<blockquote>
<p>Also, let's have a block quote!</p>
</blockquote>
</li>
<li>
<p>Item 2</p>
<p>Continuation of item 2.</p>
</li>
</ul>
<p>Separate paragraph here.</p>
Also note that the contents of list items are not wrapped in <p> tags unless there's at least one empty line among the items.
v1.5
Task lists can be made by prepending list item texts with [ ] for unchecked items or [x] for checked items.
- [ ] Do thing.
- [ ] Do other thing.
- [x] Eat ice cream.
<ul>
<li><input disabled type="checkbox"> Do thing.</li>
<li><input disabled type="checkbox"> Do other thing.</li>
<li><input checked disabled type="checkbox"> Eat ice cream.</li>
</ul>
Block Quotes
Lines starting with > (greater-than sign) denote block quotes.
> Very good, I say!
>
> Yes indeed...
<blockquote>
<p>Very good, I say!</p>
<p>Yes indeed...</p>
</blockquote>
Some block elements can be nested.
> A quote
> > containing a quote
> > - > containing a list item with a quote.
<blockquote>
<p>A quote</p>
<blockquote>
<p>containing a quote</p>
<ul>
<li>
<blockquote>
<p>containing a list item with a quote.</p>
</blockquote>
</li>
</ul>
</blockquote>
</blockquote>
Code Blocks
Code blocks can be used for pre-formatted text, e.g. for programming code.
There are two ways to denote code blocks.
Either indent the text four spaces (or a tab), or use ``` (backticks) or ~~~ (tildes) at the start and end of the text.
I am a paragraph.
local function foo(x)
bar(x < 8.6)
end
Another paragraph.
```
local function foo(x)
bar(x < 8.6)
end
```
<p>I am a paragraph.</p>
<pre><code>local function foo(x)
bar(x < 8.6)
end
</code></pre>
<p>Another paragraph.</p>
<pre><code>local function foo(x)
bar(x < 8.6)
end
</code></pre>
The latter method allows you to specify the language of the code after the initial marker.
```lua
local function foo(x)
bar(x < 8.6)
end
```
<pre><code class="language-lua">local function foo(x)
bar(x < 8.6)
end
</code></pre>
Note: Syntax highlighting for programming languages is not supported by LuaWebGen, though you can implement that yourself in a post-processing step, possibly with the help of the XML/HTML parsing module.
More backticks or tildes can be used if the code block should contain lines with clashing code block markers.
Example Markdown:
`````markdown
Let's program!
```lua
local x = foo()
```
Actually, let's not...
`````
That was a fine example.
<p>Example Markdown:</p>
<pre><code class="language-markdown">Let's program!
```lua
local x = foo()
```
Actually, let's not...
</code></pre>
<p>That was a fine example.</p>
Tables
v1.5
Tables can be created by making a table header, and having lines with cells separated by | (vertical pipe).
| Column 1 | Column 2 |
| -------- | -------- |
| Foo | Bar |
| Cute | Dogs |
<table>
<thead>
<tr>
<th>Column 1</th>
<th>Column 2</th>
</tr>
</thead>
<tbody>
<tr>
<td>Foo</td>
<td>Bar</td>
</tr>
<tr>
<td>Cute</td>
<td>Dogs</td>
</tr>
</tbody>
</table>
The cells on the second line, called the delimiter row, must contain only hyphens and optionally leading or trailing : (colons).
The delimiter row indicates that the line above is a table header and that the whole thing is indeed a table.
Use : in the delimiter row cells to indicate text alignment.
| Left-aligned | Right-aligned | Centered |
| :----------- | ------------: | :------: |
| One | Two | Three |
<table>
<thead>
<tr>
<th align="left">Left-aligned</th>
<th align="right">Right-aligned</th>
<th align="center">Centered</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">One</td>
<td align="right">Two</td>
<td align="center">Three</td>
</tr>
</tbody>
</table>
The left-most and right-most pipes can be omitted, and cells do not need to have the same width on every row.
| abc | 123456 |
-- | -----------:
Great | job
<table>
<thead>
<tr>
<th>abc</th>
<th align="right">123456</th>
</tr>
</thead>
<tbody>
<tr>
<td>Great</td>
<td align="right">job</td>
</tr>
</tbody>
</table>
Cells can be empty, or missing, or there can be too many of them (except for the header and delimiter rows which must have the same amount of cells). Pipe characters that should be part of the text can be escaped.
| hey\|ya | bo`om\|bo`x |
| ------- | ----------- |
| one |
|| two | three |
<table>
<thead>
<tr>
<th>hey|ya</th>
<th>bo<code>om|bo</code>x</th>
</tr>
</thead>
<tbody>
<tr>
<td>one</td>
<td></td>
</tr>
<tr>
<td></td>
<td>two</td>
</tr>
</tbody>
</table>
Horizontal Rules
To make a horizontal rule, put three or more - (hyphens), * (asterisks) or _ (underscores) on an isolated line.
There may be spaces between the symbols.
---
- - - - -
*****************
<hr>
<hr>
<hr>
Paragraphs
Any text not part of any other block element will become a paragraph.
Hello this is
a very
nice paragraph.
Separate multiple paragraphs with an empty line.
<p>Hello this is
a very
nice paragraph.</p>
<p>Separate multiple paragraphs with an empty line.</p>
Note how consecutive non-empty lines will be part of the same paragraph.
Span Elements
Links and Images
There are two main formats for links: inline and reference.
Inline Links
The most common format is the inline link: the link text in square brackets, followed by the destination in a parenthesis.
[Link 1](http://www.example/foo.html)
[Link 2](http://www.example/foo.html "Lemon (juice)")
[Link 3](<http://www.example/foo bar.html> (Lemon (juice)))
<p><a href="http://www.example/foo.html">Link 1</a></p>
<p><a href="http://www.example/foo.html" title="Lemon (juice)">Link 2</a></p>
<p><a href="http://www.example/foo%20bar.html" title="Lemon (juice)">Link 3</a></p>
The destination can optionally be wrapped in <>.
An optional title can be wrapped in double/single quotes or a parenthesis.
Put ! in front of the link to display an image instead.
<p><img alt="Alt text" src="http://www.example/fruits.jpg" title="Fruit basket"></p>
Reference Links
The other format, reference links, involve first declaring a link reference and then referring to the declaration where the link should be using a name.
[Name 1]: http://www.example/foo.html
[Name 2]: http://www.example/foo.html 'Lemon (juice)'
[Name 3]: <http://www.example/foo bar.html> (Lemon (juice))
- [Link 1][Name 1]
- [Link 2][Name 2]
The link text may be omitted:
[Name 2]
You can put [] after the link label
in case there are ambiguities:
[Name 1][][Name 2]
<ul>
<li><a href="http://www.example/foo.html">Link 1</a></li>
<li><a href="http://www.example/foo.html" title="Lemon (juice)">Link 2</a></li>
</ul>
<p>The link text may be omitted:
<a href="http://www.example/foo.html" title="Lemon (juice)">Name 2</a></p>
<p>You can put [] after the link label
in case there are ambiguities:
<a href="http://www.example/foo.html">Name 1</a><a href="http://www.example/foo.html" title="Lemon (juice)">Name 2</a></p>
Again in the declaration, the destination can optionally be wrapped in <>.
An optional title can be wrapped in double/single quotes or a parenthesis.
Reference link declarations must be alone on their line, and do not output any HTML by themselves.
The name, destination, and title can be on different lines, optionally indented.
[cool]
[COOL]:
/images/very-cool.jpg
"You won't believe your eyes!"
<p><a href="/images/very-cool.jpg" title="You won't believe your eyes!">cool</a></p>
Notice how the order of declaration vs. usage doesn't matter, and how the link name is case-insensitive.
Autolinks
URIs and e-mail addresses wrapped in <> are autolinks - i.e. they automatically become links.
Go to <http://www.example/> or contact
me at <hugh-jass@www.example>.
<p>Go to <a href="http://www.example/">http://www.example/</a> or contact
me at <a href="mailto:hugh-jass@www.example">hugh-jass@www.example</a>.</p>
Note that LuaWebGen tries to scramble e-mail addresses to make them less likely to be seen by address-harvesting bots.
v1.5 Plain text containing what looks like URLs or e-mail addresses will also automatically become links.
Have you been to www.foo.example recently?
Maybe try out https://bar.example/ next time!
<p>Have you been to <a href="http://www.foo.example">www.foo.example</a> recently?
Maybe try out <a href="https://bar.example/">https://bar.example/</a> next time!</p>
Text Style
Emphasis can be shown with italic, bold, or strike-through text.
| Style | Syntax | Example | Output |
|---|---|---|---|
| Italic | *text* or _text_ |
*The dog barked!?* |
The dog barked!? |
| Bold | **text** or __text__ |
**Stop!** |
Stop! |
| Strike-through v1.5 | ~~text~~ |
~~This is the ultimate truth.~~ |
|
| Nested styles | **text _text_** |
**Hey, _listen up!_** |
Hey, listen up! |
| Bold and italic | ***text*** |
***Please notice me!!!*** |
Please notice me!!! |
Code Spans
To indicate a span of code, wrap it in one or more ` (backtick quotes).
Do not call `print` too much.
<p>Do not call <code>print</code> too much.</p>
Multiple backticks can be used if the code span should contain literal backticks. The code span can also be padded with a space on each side. That space will get trimmed away.
Have you seen any `` ` `` around?
<p>Have you seen any <code>`</code> around?</p>
Plain Text
Any text without special meaning is just plain text.
Line Breaks
Hard line breaks can be inserted by escaping the line ending.
Some text here\
and also here.
<p>Some text here<br>
and also here.</p>
Inline HTML may also be used to break the line.
Over here<br>and over there.
<p>Over here<br>and over there.</p>
Inline HTML
HTML code may be embedded directly in Markdown.
Anything that "looks" like HTML will pass through the Markdown parser as HTML, including entity references (like ) and HTML comments etc.
HTML can be embedded as blocks or as spans. Here's an example of a block.
<div>
<img src="fruits.jpg">
</div>
<div>
<img src="fruits.jpg">
</div>
HTML blocks start on a line with only HTML, and (most blocks) end on the next empty line. Note that all lines after the initial HTML line will be treated as part of the HTML. Here the first two lines and the last line is seen as HTML.
<p>
**Hello**,
_world_.
</p>
<p>
**Hello**,
<p><em>world</em>.</p>
</p>
The exceptions to this rule are <script>, <pre>, and <style> tags which continue until the closest line with an appropriate end tag.
<script>
function _foo_() {}
_foo_()
</script>
<script>
function _foo_() {}
_foo_()
</script>
The same goes for <!-- -->, <? ?>, <![CDATA[ ]]> and <! >.
HTML spans can be included in any text.
**Hello**, look at my <img src="fruits.jpg">. <!-- Blah. -->
<p><strong>Hello</strong>, look at my <img src="fruits.jpg">. <!-- Blah. --></p>
Disabling Markdown Formatting
If Markdown formatting isn't wanted somewhere you can escape the relevant punctuation with \ (backslash).
\- This is not a list.
- But this is.
<p>- This is not a list.</p>
<ul>
<li>But this is.</li>
</ul>
Any punctuation can be escaped, including backslashes.
This is \<not html> but \\<this is>.
<p>This is <not html> but \<this is>.</p>
Other characters cannot, and does not need to, be escaped.
Run C:\Windows\notepad.exe for hours of fun.
<p>Run C:\Windows\notepad.exe for hours of fun.</p>
Escaping also does not work in code blocks or code spans (except for the pipe symbol in tables).
Here, have these: `\\\`. You can thank me later!
<p>Here, have these: <code>\\\</code>. You can thank me later!</p>
API
Functions
parse
html = markdown.parse( markdownText )
html = markdown( markdownText )
Convert Markdown to HTML.
Settings
addIdsToHeadings
markdown.addIdsToHeadings = bool
Whether appropriate ID attributes should be added to headings automatically or not. Default: true.
echoRaw(markdown[[
# Hello, World!
]])
-- Output if addIdsToHeadings is false: <h1>Hello, World!<h1>
-- Output if addIdsToHeadings is true: <h1 id="hello-world">Hello, World!<h1>
Page updated: 2022-04-13