Using Markdown

For the School of Data blog and many other OKF-related writing projects, Markdown is the preferred tool for formatting text. Markdown is a lightweight markup language giving authors of prose a useful range of formatting features without burdening them with a complicated syntax. WordPress’s Text editing mode supports Markdown, and we encourage blog post authors to give it a try as an alternative to HTML.

This is a quick guide to the syntax of Markdown for first-time users. See the Markdown syntax documentation for the full details.

Basics: paragraphs, headers, emphasis

Text in Markdown is divided into paragraphs. Paragraphs are separated from each other by one or more blank lines. Line breaks within paragraphs are ignored.

This is paragraph one.

This is paragraph two.
This is also paragraph two.


And this is paragraph three.

Texts are often also broken up by headers that divide the text into sections. Markdown supports up to six levels of headers. A header is created by putting a number of # signs equal to the level of the header at the start of the line.

# Title-level header (H1)
## This is an H2
###### This is an H6

Within paragraphs, you will often want to emphasize particular words. Emphasis is added by wrapping text in single or double asterisks (or underscores, equivalently). Single asterisks produce emphasized text, and double asterisks produce strong text.

*this is italicized*
_so is this_
**this is bold**
__this is too__

Hypertext: links and images

Documents written for the web often link to other websites. There are two ways to add links in Markdown. The first style, inline links, attaches the linked URL directly to the link text.

This is [an inline link](https://schoolofdata.org).

Reference links, on the other hand, attach a label to the link text, and the URL is attached to the label on a separate line which can be placed anywhere in the document. (Note that reference links use square brackets rather than parentheses.)

This is [a reference link][ref].

[ref]: https://schoolofdata.org

The Markdown syntax for inserting images is similar to that for inserting links, and it has both inline and reference styles.

![Image alt text, inline](https://schoolofdata.org/image.jpg)

![Image alt text, ref][imgref]

[imgref]: https://schoolofdata.org/image.jpg

Code

Many posts for the School of Data blog will include illustrative snippets of code. For full blocks of code, the syntax is to place four spaces (or one tab) in front of each line of code.

    let rec gcd (m,n) =
      if m = 0 then n
               else gcd (n mod m, m) ;

For inline nuggets of code (e.g “a function called pmap“), simply wrap the code fragments in backticks.

a function called `pmap`