Markdown

Markdown is a text-based markup language used for docs and other publications.

  3 minute read  

Markdown is a lightweight markup language used to create websites and other publications. Based on text, it’s an easy way to format content.

There are multiple “flavors” of Markdown, including:

Each flavor adds to the basic Markdown capabilities. [MarkdownGuide] provides a reference to the most common Markdown extensions.

In addition, there are multiple Markdown parsers, also called processors, that each vary slightly in the features they support and how they suppot them.

When working with Markdown, take time to learn the flavor and parser that you’re using. Doing so can only help you in the long run.

Here are some useful tools and resources.

Ampersand in headings

Use the HTML entity to specify an ampersand (&) in a heading:

### C# Sample

Backticks inline

To place a backtick in inline code (`), start and close your inline code block with two backticks:

`` ` ``

Comments

Markdown comments:

[//]:# (Comment text)

You can also use HTML comments (<!-- (stuff) -->).

Line breaks

To force (hard code) a line break:

  1. Leave two spaces at the end of a line

  2. Use <br> elements.

List indents

Markdown supports multi-paragraph lists; however, they can be tricky to pull off.

If you’re having problems keeping the indents straight (especially when using bulleted lists), check that:

  • You’re indenting consistently; that is, all bullets in the list have the same number of spaces in front of each bullet and each level is likewise consistent.

  • Blank lines between bullet paragraphs are indented to match the level of the following paragraph.

  • That each bullet is followed by just one space (that is, that some bullets don’t add additional spaces before the content)

  • You’re consistently using four spaces to indent child items; a single character slip can throw off the entire list.

  • You indent the starting and closing backticks of code blocks: "\n ```".

Tables

Basics

Tables require at least three lines:

| Name  | Description   |
|-------|---------------|
| Row 1 | Explanation 1 | 
| Row 2 | Explanation 2 | 
| Row 3 | Explanation 3 |

Which leads to:

Name Description
Row 1 Explanation 1
Row 2 Explanation 2
Row 3 Explanation 3

Notes:

  1. It’s not strictly necessary (or always practical) to align each column in the source. It’s easier to read (and therefore to maintain), but it’s not necessary.

  2. In the separator line, columns must be define using at least three hyphens (---).

Column alignment

| Left    | Center  | Right   |
|---------|:-------:|--------:|
| `:---`  | `:---:` | `---:`  |
| Alpha   | Apple   | Alpha   |
| Beta    | Banana  | Bravo   |
| Gamma   | Cherry  | Charlie |

Leads to:

Left Center Right
:--- :---: ---:
Alpha Apple Alpha
Beta Banana Bravo
Gamma Cherry Charlie

Syntax reference

Converting Markdown

  • GD2md-html is a Chrome extension that converts Google docs to Markdown.

  • Pandoc bills itself as your Swiss Army for converting docs from one format to another.

  • Writage is a Microsoft Word addon that converts DOC files to Markdown. Available for Mac and Windows.