H Markdown Engine

This is a markdown engine developed for my personal blog. The syntax is dialect of gfm, but not subset or superset of it.

If you're reading this document on github, some elements are not rendered properly. Please visit my blog to see the correct version.

This document is mainly focused on its markdown syntax. If you want to use this engine for your blog, read the crate's document.

[[toc]]

Things that are similar to gfm

Don't try edge cases! There must be tons of glitches.

• Thematic breaks
• Links
• Blockquotes
• ATX headings
• Task list items
  • List syntax is a bit different. Read here.
• Strikethroughs
• Images
• Hard line breaks

Things that are missing

Headers

• Setext headings are not supported.

Code blocks

• Indented codeblocks are not supported.

Autolinks

Not at all.

Raw HTMLs

• Inserting html tags is not supported, at all!
• If you want to type <, >, or &, just type as it is.
• <details> tag is not supported, but it'll be added soon.
• HTML comment <!-- --> does not work here.
  • If you want to use HTML comment tricks to divide a list, use an empty line instead.

Things that are different

Tables

Table rows and delimiter rows resemble that of gfm's table, but a bit more strict. Each cell must be enclosed by two pipes (|), including the first and the last cell. You can set its alignment using colons.

Code spans

It has limited range of syntax.

• Inline code spans use single backtick character. Multiple backtick characters're not treated as code spans.
• If you want backticks inside a code span, that's impossible.

Fenced code blocks

• Use backticks for delimiter, not tildes.
• A code fence should not be indented.
• If the first line of the fenced code is indented N spaces, then up to N spaces of indentation are removed from each line of the content (If present). (If a content line is not indented, it is preserved unchanged. If it is indented less than N spaces, all of the indentation is removed.)
  • It's similar to gfm's fenced code blocks spec, but not the same!
• A line beginning with 3 or more backticks is counted as a fence.
  • Two fences with a different number of backticks can enclose a fenced code block.
• The engine uses syntect crate for syntax highlighting.
• You can enable line-numbering with line_num(n) option. The number n designates the first index.

    ```rust, line_num(0)
    fn main() {
        println!("Hello World!");
    }

    fn add_one(n: i32) -> bool {
        n + 1
    }
    ```

fn main() {
    println!("Hello World!");
}

fn add_one(n: i32) -> bool {
    n + 1
}

Emphasis

• This engine only uses * for emphasis, not _.
  • One for italic and two for bold.

Lists

• 1., i., I., a., and A. are the only valid bullets for ordered lists.
  • Which means you cannot set its starting number.
• There must be a space between the bullet and its content.

Things that are added

Some of these extensions are from pandoc's markdown spec. The others are my custom extensions.

Underlines

~_Underlines_~ is rendered to Underlines. Underlines may not contain any newline. The first and the last character may not be space.

Subscript

H~2~O is rendered to H2O. Subscripts may not contain any space or newline.

Superscript

E=mc^2^ is rendered to E=mc^2^. Superscripts may not contain any space or newline.

Extra tags

HMD has wide variety of tags. It uses double square brackets instead of HTML's angle brackets. All the spaces inside the brackets are ignored.

Some tags have to be properly closed, or it would ruin the rendered html file! The engine does not check whether a tag is closed, so you have to take care of that. Also, be careful not to mix extra tags with other html tags. Most extra tags generate <div> or <span> tags when rendered. Those rendered tags can be mixed with auto-generated <p> tags. To prevent that you should either

• Open and close a tag within a paragraph.
• Don't use a tag as an inline element.

If you do something like below,

[[box]] A paragraph

Another paragraph [[/box]]

the result would be like below.

<p><div class="box">A paragraph</p>
<p>Another paragraph</div></p>

It would look fine on most browsers, but not desirable though.

Box

[[box]][[/box]] is rendered to <div class="box"></div>. It draws a box. You can put (almost) everything inside a box. You can even nest boxes!

[[box]]

[[center]][[big]]A box.[/big][/center]

[/box]

Font size

[[big]][[/big]] is rendered to <span class="size_big"></span>.

Font color

[[red]][[/red]] is rendered to <span class="color_red"></span>.

Not only fonts!

• [[red]][[icon=alert, size=42]][[icon=github, size=42]][/red]

Alignment

[[center]], [[left]], [[right]] tags align (almost) everything. They're rendered to <div> tag. So, don't forget to close them.

[[center]]

A centered text,

[/center] [[right]]

[[box]] and a right aligned box.[/box]

[/right]

Icons

[[icon=rust, size=128]]

You can insert icons with [[icon]] tag. The documentation can be found here.

Blank

[[blank]] is rendered to  .

Charset

Every single character in UTF-8 charset can be rendered with a [[char]] tag. [[char=9650]] is rendered to ▲, which is [[char=9650]]. It only supports decimal representation, though. Older browsers may not support some characters.

Table of contents

[[toc]] makes a table of content of the whole article. You cannot inline this tag!

Math

[[math]] x=frac{-b pm sqrt{b sup{2}-4ac}}{2a} [[/math]] is rendered to

[[center]] [[big]]

[[math]] x=frac{-b pm sqrt{b sup{2}-4ac}}{2a} [/math]

[/big] [/center]

For formulas to be rendered, <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script> should be included in the rendered HTML file. The script is not supported on IE. For IE, you should include <script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>.