Skip to content
Knowledge Base

Markdown

What is Markdown?

Section titled “What is Markdown?”
Section titled What is Markdown?
  • Markdown is a lightweight markup language
    • Other markup languages: HyperText Markup Language (HTML), Extensible Markup Language (XML), LaTeX
  • WYSIWYG: “What You See Is What You Get
    • You literally write out, what you want the text to look like
  • File extensions: .md or .markdown
  • Official markdown website: https://daringfireball.net/projects/markdown/

Note: No worries, this is not about learning HTML. The following is just an example to show the idea of markup.

In HTML:

<html>
  <body>
    <h3>headline level 3</h3>
    <h4>headline level 4</h4>
  </body>
</html>

In Markdown:

  ### headline level 3
  #### headline level 4

Rendered output:

headline level 3

Section titled “headline level 3 ”
Section titled headline level 3

headline level 4

Section titled “headline level 4 ”
Section titled headline level 4

In HTML:

  <ul>
    <li>List item 1</li>
    <li><strong>List item 2 in bold</strong></li>
  </ul>

In Markdown:

  - List item 1
  - **List item 2 in bold**

Rendered output:

  • List item 1
  • List item 2 in bold

Why Markdown?

Section titled “Why Markdown?”
Section titled Why Markdown?
  • simple, plain text format
    • no hassle with formatting
    • Worry about content, not layout.
    • Most benefits of LaTeX, but simpler
  • easy-to-read, easy-to-write
    • intuitively human-readable
    • machine-actionable, convertible
  • independent
    • open source
    • You only need a text editor
    • No need for “word processor programs”
      • Microsoft Word, WordPad, macOS Pages, Google Docs, LibreOffice Writer
  • reusable
    • text is not stuck in formats or layouts
  • extendible
    • many programs and tools work with markdown

Is there anything markdown can’t do?

Section titled “Is there anything markdown can’t do?”
Section titled Is there anything markdown can’t do?
  • Beautiful, perfectly designed documents or slide shows
    • Reminder: “WYSIWYG”
    • Theming, customization, special formatting, design is hard(ly possible)
    • Use a word processor (or LaTeX ;-) )
  • Collaboration on documents (e.g. reviewing manuscripts)
    • comments, suggestions, discuss changes, text highlighting

Markdown <> Code & Data Management?

Section titled “Markdown <> Code & Data Management?”
Section titled Markdown &lt;&gt; Code &amp; Data Management?
  • Works perfectly with (text based) version-control (-> git)
  • Many GitHub / GitLab features are based on MD
    • README.md, issues, wiki pages, discussions and comments
    • referencing files and folders, e.g. in a README.md
  • Structuring and commenting code supported by IDEs1, e.g.
    • Jupyter Notebooks ~ markdown-commented python scripts
    • RMarkdown ~ markdown-commented R scripts

Implementations and variants

Section titled “Implementations and variants”
Section titled Implementations and variants

Markdown can be used in many programming languages, platforms and frameworks, incl.:

Note: There are different flavors to how and what is “interpreted”,
e.g. not every markdown parser understands

  • bold html text
  • emojis :bike:, :beers:, :tent:
  • or footnotes2

Converting markdown files

Section titled “Converting markdown files”
Section titled Converting markdown files

In case you want to provide your markdown document in another file format, converters help you. The top recommendation: Pandoc.3

Note: pandoc conversion to pdf depends on a LaTeX Installation on your system. If you run into issues, see https://pandoc.org/installing.html for details and recommendations.

Use pandoc to convert your…

Terminal window
pandoc README.md -o markdown_intro.html   # ... markdown to .html
pandoc README.md -o markdown_intro.pdf    # ... markdown to .pdf
pandoc README.md -o markdown_intro.docx   # ... markdown to .docx
pandoc -t slidy -s --slide-level=2 --metadata pagetitle=markdown_intro README.md -o markdown_intro_slides.html # ... markdown to html slides

Real-time collaboration

Section titled “Real-time collaboration”
Section titled Real-time collaboration

Although markdown is not perfect for collaboration on documents (e.g. manuscripts), there are occasions where online collaboration in markdown format comes in very handy (meetings with people that understand MD, code-intensive classes, etc.).

Tutorials and resources

Section titled “Tutorials and resources”
Section titled Tutorials and resources
Section titled “Recommended VS code extensions”
Section titled Recommended VS code extensions

There are many markdown extensions available for Visual Studio Code.
These support you in

Hands-on markdown tutorial

Section titled “Hands-on markdown tutorial”
Section titled Hands-on markdown tutorial

mostly (adapted) from https://daringfireball.net/projects/markdown/dingus

Software

Section titled “Software”
Section titled Software

Try writing a markdown document, using either

  1. an online markdown editor (e.g. https://demo.hedgedoc.org/new),
  2. the GitHub or GitLab IDE to create / adapt the README.md, or
  3. (advanced) your favorite text-editor that supports markdown.

Basic Syntax

Section titled “Basic Syntax”
Section titled Basic Syntax

Phrase Emphasis

Section titled “Phrase Emphasis”
Section titled Phrase Emphasis
Terminal window
*This is italic*
_This is also italic_
**This is bold**
__This is also bold__

Headers

Section titled “Headers”
Section titled Headers
Terminal window
# Header 1


## Header 2


###### Header 6

Lists

Section titled “Lists”
Section titled Lists

Ordered, without paragraphs:

Section titled “Ordered, without paragraphs:”
Section titled Ordered, without paragraphs:
Terminal window
1. Item 1
2. Item 2
4. Item 3

Note the “4.” in md

Unordered, with paragraphs:

Section titled “Unordered, with paragraphs:”
Section titled Unordered, with paragraphs:
Terminal window
- A list item.
- Bar
You can nest them:
- Abacus
  * answer
  * Bubbles
    1. bunk
    2. bupkis
      - BELITTLER
    3. burper

Note: indentation matters

Blockquotes

Section titled “Blockquotes”
Section titled Blockquotes
```
> Email-style angle brackets
> are used for blockquotes.


> > And, they can be nested.


> #### Headers in blockquotes
>
> - You can quote a list.
> - Etc.
```

Code Spans

Section titled “Code Spans”
Section titled Code Spans
```
- `<code>` spans are delimited by backticks.


- You can include literal backticks like `` `this` ``.
```

Code Blocks

Section titled “Code Blocks”
Section titled Code Blocks
```
This is a code block
```

Horizontal Rules

Section titled “Horizontal Rules”
Section titled Horizontal Rules

Three or more dashes or asterisks:

---


* * *


- - - -

Manual Line Breaks

Section titled “Manual Line Breaks”
Section titled Manual Line Breaks
Terminal window
End a line with two or more spaces:
Roses are red,
Violets are blue.
Section titled “Links”
Section titled Links
Terminal window
- Inline:
  An [example](http://url.com/ "Title")


- Reference-style labels (titles are optional):
  An [example][id]. Then, anywhere else in the doc, define the link:


  [id]: http://example.com/  "Title"

Images

Section titled “Images”
Section titled Images
Terminal window
![alt text](../../../assets/images/core-concepts/arc-builds-on-standards.png "This is an ARC")

alt text

Footnotes

Section titled “Footnotes”
Section titled Footnotes

  1. Integrated development environments ↩

  2. I am a footnote ↩

  3. https://pandoc.org/ “Pandoc” ↩