This document shows examples of some of the specialized blocks we usen when writing Markdown for the Free PDK documentation. We use Kramdown for Markdown parsing. Kramdown has a handy quick reference for the most important Markdown features.

Table of Contents

  1. Callouts
  2. Footnotes
  3. Markdown inside HTML
  4. Table of Contents

:link: Callouts

Callouts are used to highlight important or missing information. You should always specify markdown="1" like in the examples (even if you don’t want to use markdown inside the callout) so that the padding of the callout is correct.

Correct

<div class="callout" markdown="1">
  **Hey!** Watchout for trains!
</div>

Hey! Watchout for trains!

Lists work as well:

<div class="callout" markdown="1">
  - foo
  - bar
</div>
  • foo
  • bar

Incorrect

<div class="callout">
  Hey! Watchout for trains!
</div>
Hey! Watchout for trains!

:link: Footnotes

Kramdown supports named footnotes. Footnotes are inserted using [^name-of-the-footnote]. The content of the footnote can be placed anywhere you see fit, but is always rendered at the very bottom of the page. Make sure to indent the footnote content by exactly 4 spaces like shown below.

Trains are fast[^my-footnote]. Or are they[^my-footnote]?

[^my-footnote]:
    **Yup, they are really fast.**
    You can even write multiple lines.

Trains are fast1. Or are they1?

:link: Markdown inside HTML

By default, Kramdown doesn’t process content within HTML tags: To process Markdown within HTML, set the special markdown attribute to 1, block, or span. The difference between them is explained in detail in the Kramdown Documentation.

Correct

<div markdown="1">
  *test*
</div>

test

Incorrect

<div>
  *test*
</div>
*test*

:link: Table of Contents

To embed a table of contents, use

{% include toc.md %}

Table of Contents

  1. TOC Placeholder

To exclude a header from the table of contents, use the {:.no_toc} attribute:

# My Header
{:.no_toc}

  1. Yup, they are really fast. You can even write multiple lines. ↩ ↩2