Our Markdown Style Guide

Published on: August 10, 2022

This post serves as a reference style guide for how we use markdown. It covers the available options, tags, and shortcodes we use internally.

Headers

Semantically, only a single H1 header should be present on a page. When defining sub-headers, use the next highest header in order.

# Header 1
## Header 2
### Header 3
#### Header 4
## Header 2
### Header 3
### Header 3
#### Header 4
##### Header 5
###### Header 6

Emphasis

Avoid over use of emphasis within content. For styling purposes large portions of text should be modified with CSS classes.

Italics are assigned with *asterisks* or _underscores_

Strong is assigned with double **asterisks** or double __underscores__

You can combined emphasis like **asterisks and _underscores_**

Strikethrough uses double tildes ~~strikethrough~~

Emphasis Examples

• italics
• strong
• combined emphasis
• strikethrough

Lists

Ordered Lists
1. First
2. Second
3. Third

Unordered Lists
- Item 1
- Item 2
    - Sub-Item 1
    - Sub-Item 2
- Item 3

Links

[Inline Link](https://session0.dev)

[Inline Link w/ Title](https://session0.dev "Session0")

[Relative Link](/about-us)

Link Examples

• Inline Link
• Inline Link w/ Title
• Relative Link

Images

For images we use our own custom picture shortcode using modern HTML5 semantics.

Warning: Do NOT hotlink to external images.

{{</* picture src="images/internal-image.png" alt="Image Alt Text" */>}}

Code/Syntax Hightlighting

{{< highlight markdown >}}

const example = "This highlights Javascript syntax.";
console.log(example);

fn main() {
    println!("Hello, world!");
}

example = "This highlights Python syntax."
print(example)

{{< / highlight >}}

Javascript Example

const example = "This highlights Javascript syntax.";
console.log(example);

Rust Example

fn main() {
    println!("Hello, world!");
}

Python Example

example = "This highlights Python syntax."
print(example)

Additional syntax highlighting information from Hugo

Tables

| index  | key         | data  |
| ------ |:-----------:| -----:|
| 0      | some-key    | this  |
| 1      | another-key | is a  |
| 2      | final-key   | table |

Example Table

Blockquotes

Used for quotes or highlight reply text. Prefix text with a greater-than (>) symbol.

> This is an example blockquote.

This is an example blockquote.

Thematic Break (Horizontal Rule)

MDN Description:

The

---

HTML element represents a thematic break between paragraph-level elements: for example, a change of scene in a story, or a shift of topic within a section.

You can create horizontal rules using three dashes.
---

Below is an example horizontal rule.

Inline HTML

Avoid using inline HTML inside our markdown files. Instead opt for a custom shortcode for short and repeatable elements.

Table of Contents

To add a table of contents to a post, add the following variable to the frontmatter:

toc: true

Footnotes

You can create footnotes for references within an article using the following markdown:

This sentence has an example footnote.[^1]

Another sentence with a footnote.[^2]

[^1]: Our footnote reference.
[^2]: Our second footnote reference.

This sentence has an example footnote.¹

Another sentence with a footnote.²