let rec weng = ~weng cv misc contact blog 博客

Using HTML tags in Markdown (Kramdown)


λ. TL;DR

  1. Kramdown, used by Jekyll, supports raw HTML tag and attribute markdown=1 to parse its inner content.
  2. In markdown, indented code blocks is made by indentation.
  3. Indented content of raw HTML tag <div> will be treated as code.

λ. 1. Backgroud

Markdown is a lightweight markup language. It has a few extensions, or dialects, e.g. GFM (GitHub Flavored Markdown). Jekyll is a static site generator that is used as a default for GitHub Pages. Jekyll is written in Ruby and it uses another Ruby library Kramdown to parse and convert markdown.

This blog is currently written in these toolchains. I was trying to add some custom layout tuning for my pages written in GFM, by embeding html tags so that I can control their appearance.

λ. 2. HTML blocks in Markdown

The original Markdown syntax specifies that an HTML block must start at the left margin, i.e. no indentation is allowed. Also, the HTML block has to be surrounded by blank lines. Both restrictions are lifted for kramdown documents. Additionally, the original syntax does not allow you to use Markdown syntax in HTML blocks which is allowed with kramdown.

– Difference to Stardard Markdown [doc]

It’s almost the quote-quasiquote game that occurs in markdown. kramdown support HTML tag attribute markdown="<val>" that means the content of this tag is raw HTML (0), markdown (1) and others.

λ. 3. Code blocks

I usually use fenced code blocks (code) so I forgot indented code blocks can also be made by indenting four spaces, e.g.

I am the bone of my sword.
Steel is my body, and fire is my blood.

I don't find out how to set the **language identifier **
for indented code block

λ. 4. Experiments

These experiments are performed at kramdown 2.3.2 (kramdown-parser-gfm 1.1.0). Note <span> is an inline element so it breaks some styling of this post but let’s ignore it.

λ. 4.1 Raw HTML without attribute markdown='1'

<div>I am raw **markdown** in (div). </div>
I am raw **markdown** in (div).

<span>I am raw **markdown** in (span). </span>

I am raw markdown in (span).

<p>I am raw **markdown** in (p). </p>

I am raw **markdown** in (p).

λ. 4.2 Raw HTML with attribute markdown='1'

<div markdown='1'>I am **markdown** in (div). </div>

I am markdown in (div). </div>

<span markdown='1'>I am **markdown** in (span). </span>

I am markdown in (span).

<p markdown='1'>I am **markdown** in (p). </p>

I am markdown in (p).

λ. 4.3 Indented code in HTML without attribute markdown='1'

    I am **code** in (div). 
I am **code** in (div).

    I am **code** in (p). 

I am code in (p).

    I am **code** in (p). 

I am **code** in (p).

λ. 4.4 Indented code in HTML with attribute markdown='1'

<div markdown='1'>
    I am **code** in (div). 
I am **code** in (div). 

<span markdown='1'>
    I am **code** in (p). 

I am code in (p).

<p markdown='1'>
    I am **code** in (p). 

I am code in (p).

λ. 4.5 Observations

Vanilla <span> can parse its inner markdown content.

Only <div markdown='1'> can parse indented content as code.

For other tags and non-indented content, HTML tags must set markdown='1' to parse its markdown content, otherwise the content is treated literally.

Using HTML tags in Markdown (Kramdown)