λ. TL;DR
- Kramdown, used by Jekyll, supports raw HTML tag and attribute
markdown=1
to parse its inner content. - In markdown, indented code blocks is made by indentation.
- Indented content of raw HTML tag
<div>
will be treated ascode
.
λ. 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>
<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'
<div>
I am **code** in (div).
</div>
<span>
I am **code** in (p).
</span>
I am code in (p).
<p>
I am **code** in (p).
</p>
I am **code** in (p).
λ. 4.4 Indented code in HTML with attribute markdown='1'
<div markdown='1'>
I am **code** in (div).
</div>
I am **code** in (div).
<span markdown='1'>
I am **code** in (p).
</span>
I am code in (p).
<p markdown='1'>
I am **code** in (p).
</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.