Notes

Markup for “kramdown”

The static site generator Jekyll on GitHub Pages uses “kramdown” as the Markdown renderer. It converts a superset of Markdown.

Below are examples of all available structural elements that can be used in a kramdown text, taken from kramdown Quick Reference (excluding “Block Attributes,” “Inline Attributes” and “Extensions”). There is also more information at kramdown Syntax. This reference is for kramdown version 1.16.2, the version used by GitHub Pages at this time.

The example markup is also useful for testing that the Jekyll theme in use styles the output.


Kramdown Reference

Block-level Elements

Paragraphs

Consecutive lines of text are considered to be one paragraph. As with other block level elements you have to add a blank line to separate it from the following block-level element:

The first paragraph.

Another paragraph.

The first paragraph.

Another paragraph.

Explicit line breaks in a paragraph can be made by using two spaces or two backslashes at the end of a line:

This is a paragraph  
which contains a hard line break.

This is a paragraph
which contains a hard line break.

Headers

kramdown supports Setext style headers and atx style headers. A header must always be preceded by a blank line except at the beginning of the document:

First level header
==================

Second level header
-------------------

First level header

Second level header

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Blockquotes

A blockquote is started using the > marker followed by an optional space; all following lines that are also started with the blockquote marker belong to the blockquote. You can use any block-level elements inside a blockquote:

> A sample blockquote.
>
> > Nested blockquotes are also possible.
>
> ## Headers work too
> This is the outer quote again.

A sample blockquote.

Nested blockquotes are also possible.

Headers work too

This is the outer quote again.

You may also be lazy with the > markers as long as there is no blank line:

> This is a blockquote
continued on this
and this line.

But this is a separate paragraph.

This is a blockquote continued on this and this line.

But this is a separate paragraph.

Code Blocks

kramdown supports two different code block styles. One uses lines indented with either four spaces or one tab whereas the other uses lines with tilde characters as delimiters — therefore the content does not need to be indented:

This is a sample code block.

~~~~~~
This is also a code block.
~~~
Ending lines must have at least as
many tildes as the starting line.
~~~~~~~~~~~~
This is also a code block.
~~~
Ending lines must have at least as
many tildes as the starting line.

The following is a code block with a language specified:

~~~ ruby
def what?
	42
end
~~~
def what?
	42
end

Lists

kramdown supports ordered and unordered lists. Ordered lists are started by using a number followed by a period, a space and then the list item text. The content of a list item consists of block-level elements. All lines which have the same indent as the text of the line with the list marker belong to the list item:

1. This is a list item
2. And another item
2. And the third one
	with additional text
  1. This is a list item
  2. And another item
  3. And the third one with additional text

As with block quotes, you may be lazy when using the list item marker:

* A list item
with additional text
  • A list item with additional text

As the content consists of block-level elements you can do things like the following:

1.  This is a list item

	> with a blockquote

	## And a header

2.  Followed by another item
  1. This is a list item

with a blockquote

And a header

  1. Followed by another item

Nested lists are also easy to create:

1. Item one
   1. sub item one
   2. sub item two
   3. sub item three
2. Item two
  1. Item one
    1. sub item one
    2. sub item two
    3. sub item three
  2. Item two

Lists can occur directly after other block-level elements, however, there has to be at least one blank line if you want to follow a paragraph with a list:

This is a paragraph.
1. This is NOT a list.

1. This is a list!

This is a paragraph.

  1. This is NOT a list.

  2. This is a list!

Unordered lists are started by using an asterisk, a dash or a plus sign (they can be mixed) and a space. Apart from that unordered lists follow the same rules as ordered lists:

* Item one
+ Item two
- Item three
  • Item one
  • Item two
  • Item three

Definition Lists

A definition list works similar to a normal list and is used to associate definitions with terms. Definition lists are started when a normal paragraph is followed by a line starting with a colon and then the definition text. One term can have many definitions and multiple terms can have the same definition. Each line of the preceding paragraph is assumed to contain one term, for example:

term
: definition
: another definition

another term
and another term
: and a definition for the term
term
definition
another definition
another term
and another term
and a definition for the term

If you insert a blank line before a definition (note: there must only be one blank line between the terms and the first definition), the definition will be wrapped in a paragraph:

term

: definition
: definition
term

definition

definition

Each term can be styled using span-level elements and each definition is parsed as block-level elements, i.e. you can use any block-level in a definition. Just use the same indent for the lines following the definition line:

This *is* a term

: This will be a paragraph
	
	> a blockquote
	
	## A header
This is a term

This will be a paragraph

a blockquote

## A header

Tables

kramdown supports a syntax for creating simple tables. A line starting with a pipe character (|) starts a table row. However, if the pipe characters is immediately followed by a dash (-), a separator line is created. Separator lines are used to split the table header from the table body (and optionally align the table columns) and to split the table body into multiple parts. If the pipe character is followed by an equal sign (=), the tables rows below it are part of the table footer.

| A simple | table |
| with multiple | lines |
A simple table
with multiple lines
| Header 1 | Header 2 | Header 3 |
|:---------|:--------:|---------:|
| cell 1   | cell 2   | cell 3   |
| cell 4   | cell 5   | cell 6   |
|----
| cell 1   | cell 2   | cell 3   |
| cell 4   | cell 5   | cell 6   |
|=====
| foot 1   | foot 2   | foot 3
Header 1 Header 2 Header 3
cell 1 cell 2 cell 3
cell 4 cell 5 cell 6
cell 1 cell 2 cell 3
cell 4 cell 5 cell 6
Foot 1 Foot 2 Foot 3

HTML Elements

kramdown allows you to use block-level HTML tags (div, p, pre, …) to markup whole blocks of text — just start a line with a block-level HTML tag. kramdown syntax is normally not processed inside an HTML tag but this can be changed with the parse_block_html option. If this options is set to true, then the content of a block-level HTML tag is parsed by kramdown either as block level or span-level text, depending on the tag:

{::options parse_block_html="false" /}

<div style="float: right">
Something that stays right and is not wrapped in a paragraph.
</div>

{::options parse_block_html="true" /}

<div>
This is wrapped in a paragraph.
</div>
<p>
This can contain only *span* level elements.
</p>
Something that stays right and is not wrapped in a paragraph.

This is wrapped in a paragraph.

This can contain only span level elements.

Span-Level Elements

Emphasis

Emphasis can be added to text by surrounding the text with either asterisks or underscores:

This is *emphasized*, _this_ too!

This is emphasized, this too!

Strong emphasis can be done by doubling the delimiters:

This is **strong**, __this__ too!

This is strong, this too!

The form with the asterisks can also be used to markup parts of words:

This w**ork**s as expected!

This works as expected!

A simple link can be created by surrounding the text with square brackets and the link URL with parentheses:

A [link](http://kramdown.gettalong.org) to the kramdown homepage.

A link to the kramdown homepage.

You can also add title information to the link:

A [link](http://kramdown.gettalong.org "hp") to the homepage.

A link to the homepage.

There is another way to create links which does not interrupt the text flow. The URL and title are defined using a reference name and this reference name is then used in square brackets instead of the link URL:

A [link][kramdown hp] to the homepage.

[kramdown hp]: http://kramdown.gettalong.org "hp"

A link to the homepage.

If the link text itself is the reference name, the second set of square brackets can be omitted:

A link to the [kramdown hp].

[kramdown hp]: http://kramdown.gettalong.org "hp"

A link to the kramdown hp.

Images

Images can be created in a similar way: just use an exclamation mark before the square brackets. The link text will become the alternative text of the image and the link URL specifies the image source:

An image: ![grass](https://kramdown.gettalong.org/img/image.jpg)

An image: grass

Inline Code

Text phrases can be easily marked up as code by surrounding them with backticks:

Use `Kramdown::Document.new(text).to_html` to convert the text in kramdown syntax to HTML.

Use Kramdown::Document.new(text).to_html to convert the text in kramdown syntax to HTML.

If you want to use literal backticks in your code, just use two or more backticks as delimiters. The space right after the beginning delimiter and the one right before the closing delimiter are ignored:

Use backticks to markup code, e.g. `` `code` ``.

Use backticks to markup code, e.g. `code`.

Footnotes

Footnotes can easily be used in kramdown. Just set a footnote marker (consists of square brackets with a caret and the footnote name inside) in the text and somewhere else the footnote definition (which basically looks like a reference link definition):

This is a text with a footnote.[^1]

[^1]: And here is the definition.

This is a text with a footnote.1

The footnote definition can contain any block-level element, all lines following a footnote definition indented with four spaces or one tab belong to the definition:

This is a text with a footnote.[^2]

[^2]:
	And here is the definition.

	> With a quote!

This is a text with a footnote.12

As can be seen above the footnote name is only used for the anchors and the numbering is done automatically in document order. Repeated footnote markers will link to the same footnote definition.

Abbreviations

Abbreviations will work out of the box once you add an abbreviation definition. So you can just write the text and add the definitions later on.

This is an HTML example.

*[HTML]: Hypertext Markup Language

This is an HTML example.

HTML Elements

HTML is not only supported on the block-level but also on the span-level:

This is <span style="color: tomato">written in tomato</span>.

This is written in tomato.


Notes

  • kramdown also renders checklists (- [ ], - [x] or 1. [ ]) as disabled and checked checkboxes:

    • do
    • done

    And:

    1. do this first
    2. done
  • kramdown does not process :: for <mark> (highlights), as in ::highlighted:: (but this Jekyll theme filters for marks):

    highlight

  • It doesn’t output <figure> and <figcaption> for Markdown images with descriptions (![image description](/some/img.jpg)) and it won’t render figure tags in the Markdown when parse_block_html is true (but this Jekyll theme filters for images with descriptions and renders figures in their place):

    grass
    grass
  • It doesn’t handle audio or video, so put those html elements directly in Markdown (with download link as fallback for older browsers): <video src="" controls><a href="" download>Download video</a></video> and <audio src="" controls><a href="" download>Download audio</a></audio>

  1. And here is the definition.  2

  2. And here is the definition.

    With a quote!