Writing in markdown

How to write documents using Markdown syntax

Markdown is a simple syntax for formatting text and adding graphics to documentation. Writing documentation using syntax (rather than Microsoft Word, for example), makes it easy for different programs to interpret what you have written and display it according to fixed rules. A markdown document can be easily transferred to a Word document, a pdf, and back again. By contrast, have you ever tried to copy-past from a pdf into Word?! Some characters just don’t translate…

Using markdown also supports you to use “heading” identifiers, rather than simply changing the font size. This is because it is so easy to use heading syntax and it is comparatively complex to change a font size! This makes for content which is more accessible to screen readers used by individuals with a visual impairment ✌🏻 ✌🏼 ✌🏽 ✌🏾 ✌🏿

Markdown is used by GitHub to translate your text and formatting into webpage (GitHub Pages) content. You will be writing your documentation (maybe in Atom) using markdown syntax, and it will automatically be rendered into something beautiful on your Pages site.

There are many markdown tutorials online which you can follow. I’ve listed the syntax I use most commonly below:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

![image alt text](image path)

*italic*
**bold**
***italic bold**

P.S. There is no shame in having a markdown cheat-sheet pinned to your virtual or physical wall 😉