Introduction to Markdown

• What is Markdown?
• Why Markdown?
• Is there anything markdown can't do?
• Markdown <> Code & Data Management?
• Implementations and variants
• Converting markdown files
• Real-time collaboration
• Tutorials and resources
• Recommended VS code extensions
• Hands-on markdown tutorial
• Software
• Basic Syntax
  • Phrase Emphasis
  • Headers
  • Lists
    • Ordered, without paragraphs:
    • Unordered, with paragraphs:
  • Blockquotes
  • Manual Line Breaks
  • Links
  • Images

• 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:

In Markdown:

Rendered output:

In HTML:

In Markdown:

Rendered output:

• List item 1
• List item 2 in bold

• 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

• 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

• 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 IDEs¹, e.g.
  • Jupyter Notebooks ~ markdown-commented python scripts
  • RMarkdown ~ markdown-commented R scripts

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

• GitHub (see GitHub Flavored Markdown)
• Gitlab
• Microsoft Team Chats
• Stack Exchange
• RStudio (see RMarkdown)
• Website generators (forget WordPress)

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

• bold html text
• emojis 🚲, 🍻, ⛺
• or footnotes²

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

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...

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.).

• HedgeDoc: https://hedgedoc.org
• CodiMD https://github.com/hackmdio/codimd

• Markdown Guide: https://www.markdownguide.org/
• Commonmark Tutorial: https://commonmark.org/help/tutorial/
• Cheat sheets:
  • https://www.markdownguide.org/cheat-sheet/
  • https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
  • https://daringfireball.net/projects/markdown/dingus
• Markdown emojis https://gist.github.com/rxaviers/7360908

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

• Creating a table, copy/pasting a table from excel

• Converting a markdown to PDF

• Structuring and formatting

• Creating a TOC

• Use shortcuts

• Microsoft Docs Authoring Pack, including

  • markdownlint
  • Code Spell Checker

• Markdown Shortcuts

• Markdown PDF

• Markdown all in one

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

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.

Note the "4." in md

Note: indentation matters

```
> Email-style angle brackets
> are used for blockquotes.

> > And, they can be nested.

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

```
- `<code>` spans are delimited by backticks.

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

```
This is a code block
```

Three or more dashes or asterisks:

DataPLANT Support