markdown

Markdown parser demo

This example is showcasing some features of the Markdown parser of @thi.ng/hiccup-markdown package. Depending on device, the right or bottom half is showing a realtime preview of the source document in the other half.

Live demo | Source code

Syntax features & extensions

Blockquotes

Nested blockquotes are supported and can contain links, images and inline formatting, but not other block elements (e.g. lists):

Nesting is supported:

"To understand recursion, one must first understand recursion." — Stephen Hawking

Images in blockquotes are ok too:

etc.

Code block headers

Code blocks can have additional space-separated fields in the header which are being passed to the tag handler (but which we ignore here in this example):

// clever code here

Custom blocks

This is a non-standard Markdown syntax extension for custom freeform content:

:::info Custom block example In this example we're parsing the contents of these custom blocks as Markdown itself, but the overall idea is to enable all sorts of additional "rich" content (UI components, visualizations, media players etc.) :::

:::warn Custom block example Each block has its own type (the 1st word in the block header). The example handler only supports info or warn types... :::

Emoji names

The familiar :emoji_name: syntax can be used to include emojis in body text. We're using from thi.ng/emoji for look ups (source data from node-emoji). Kewl! 😎

Footnotes

Footnotes are supported, but this statement might need some further explanation¹.

Formatting

To avoid ambiguity and simplify nesting, only the following formatting syntax is supported for bold & italic:

• **bold**
• _italic_
• code (`) and strikethrough (~~) as usual...
• <kbd> for keyboard shortcuts (e.g. Control)
• <sub> for _subscript
• <sup> for ^superscript

Headings {#custom-header-id}

Only ATX-style headings (aka lines prefixed with #) are supported (levels 1-6). The parser supports {#custom-id}-style line suffixes for headings, which are passed as separate anchorID param to the element handlers. If not specified in the Markdown source, the parser auto-generates this ID (with no uniqueness guarantee) based on slugifying the heading's body content (Github readme compatible).

For example, here is a link to this section (using ID #custom-header-id).

Images

Alt text for images is required. Optional title attribute (e.g. for hover tooltip or caption) can be given in quotes after the image URL. For example:

![alt text](url "title text")

Link formats

The following link formats are supported:

1. [label](target)
2. [label](target "title")
3. [label][ref-id] - the reference ID will have to provided somewhere else in the document or pre-defined via options given to the parser
4. [[page name]] - Wiki-style page reference, non-standard Markdown
5. [[page name|label]] - like 4., but with added link label

Lists

• Ordered and unordered lists are supported
  • Fully nestable
• Ordered lists start with a 1. (digit or letter followed by a dot) prefix
• Unordered lists must use a - line prefix
• TODO list items
  • ...are supported as well

Blocklevel metadata

Arbitrary metadata can be assigned to any blocklevel element:

• blockquotes
• code blocks
• custom blocks
• headings
• horizontal rules
• lists
• paragraphs
• tables

See the package readme for more details. Here's an example of metadata assigned to a headline:

{{{ some freeform metadata }}}

Amazing example headline title

...and another one with a custom block:

{{{ date=2023-02-25 status=done }}} :::foo Example block title Just checkout that metadata... :::

Tables

Cells in...	header are treated separately
Column alignments	✅ supported
Inline formats	✅ supported and nestable
Images
Links	✅ supported
Unsupported	❌ linebreaks
	❌ lists
	❌ blockquotes

Onwards!

Please see the package readme & API docs for further details. If you've got any questions, please use the thi.ng/umbrella discussion forum or issue tracker...

---

Footnotes

1. ...or does it really?! 😉 ↩