markdown.md 8.32 KB
Newer Older
1
2
---
layout: page
Laurent Heirendt's avatar
Laurent Heirendt committed
3
4
permalink: /external/contribute/markdown/
shortcut: contribute:markdown
5
redirect_from:
Laurent Heirendt's avatar
Laurent Heirendt committed
6
  - /cards/contribute:markdown
Laurent Heirendt's avatar
Laurent Heirendt committed
7
  - /external/cards/contribute:markdown
8
---
Laurent Heirendt's avatar
Laurent Heirendt committed
9
10
11
12
# Markdown

Markdown is a lightweight markup language with plain text formatting syntax which became very popular in past decade and which nowadays serves as a standard in various digital communication channels.

Laurent Heirendt's avatar
Laurent Heirendt committed
13
## Main features of Markdown
Laurent Heirendt's avatar
Laurent Heirendt committed
14

Laurent Heirendt's avatar
Laurent Heirendt committed
15
16
17
18
19
20
21
22
23
* It has very simple syntax easy to learn.
* It is already widely used in scientific community.
* It separates content from visual presentation so it allows you to focus on writing, not formatting.
* It is a non-proprietary file format.
* It is powerful - allows to format text with very little effort.
* It is portable - since it is actually plain text, it can be opened by literally all text editors.
* It is machine readable - as simple text, markdown documents can be tracked and version using a versioning system (Git, SVN)
* small file size
* easy to convert to other formats - existing editors and command line tools (e.g. [pandoc](https://pandoc.org/) allows for easy conversion between Markdown and other widely used formats like HTML, PDF, docx, LaTeX, etc.
Laurent Heirendt's avatar
Laurent Heirendt committed
24
25

## Quick reference
26

Laurent Heirendt's avatar
Laurent Heirendt committed
27
28
29
* The following symbol <img src="img/visual-code_img_9.png" height="20"> behind the file name means that your changes/writing is not saved. Press CTRL+S to save your procedure
* To preview your writing click on:
  <img src="img/visual-code_img_10.png">
Laurent Heirendt's avatar
Laurent Heirendt committed
30

Jacek Lebioda's avatar
Jacek Lebioda committed
31
## Tips to write in markdown:
Vilem Ded's avatar
Vilem Ded committed
32

Laurent Heirendt's avatar
Laurent Heirendt committed
33
34
35
36
37
38
39
40
41
42
43
| Markdown                           | Rendered Output           |
|:-----------------------------------|---------------------------|
|: <pre># Header 1</pre>              | # Header 1
|: <pre>## Header 2</pre>             | ## Header 2
|: <pre>### Header 3</pre>            | ### Header 3
|: <pre>#### Header 4</pre>           | #### Header 4
|:-----------------------------------|---------------------------|
|: <pre>To make a text **bold**: use **double asterisk** or __underscores__</pre> | To make a text **bold**, use **double asterisk** or __underscores__ before and after a word or phrase. |
|:-----------------------------------|---------------------------|
|: <pre>To make a text *italic*: use *one asterisk* or _underscore_.</pre> | To make a text **italic**, use *one asterisk* or _underscore_.|
|:-----------------------------------|---------------------------|
Laurent Heirendt's avatar
Laurent Heirendt committed
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|: Use numbers for ordered lists     |
|: ^^<pre>1. First item              | ^^ 1. First item
|: ^^1. Second item                  | ^^ 1. Second item
|: ^^1. Third item                   | ^^ 1. Third item
|: ^^     1. Indented item           | ^^     1. Indented item
|: ^^     1. Indented item           | ^^     1. Indented item
|: ^^1. Fourth item </pre>           | ^^1. Fourth item
|:-----------------------------------|---------------------------|
|: For unordered lists use asterisk, minus or plus |
|: ^^<pre>- First item               | ^^ - First item
|: ^^- Second item                   | ^^ - Second item
|: ^^* Third item                    | ^^ * Third item
|: ^^     * Indented item            | ^^      * Indented item
|: ^^     + Indented item            | ^^      + Indented item
|: ^^* Fourth item</pre>             | ^^ * Fourth item
|:-----------------------------------|---------------------------|
|: <pre>Include links referring to a web [page](https://www.markdownguide.org/)</pre> | Include links referring to a web [page](https://www.markdownguide.org/)
|:-----------------------------------|---------------------------|
|: Include local pictures using markdown |
|: ^^<pre>![My awesome picture](img/r3_logo.png)</pre> | ^^ ![My awesome picture](img/r3_logo.png)
|: Or use HTML tag allowing you to alter the image properties (e.g. size) |
|: ^^<pre>&lt; img src="img/r3_logo.png" width="40" &gt;</pre> | ^^<img src="img/r3_logo.png" width="40">
|:-----------------------------------|---------------------------|
|: Include code blocks!              |
|: ^^ <pre>\`\`\`                    | ^^
|: ^^def function(x):                | ^^<pre>def function(x):
|: ^^  x+1                           | ^^    x+1
|: ^^function(2)                     | ^^function(2)
|: ^^\`\`\`</pre>                    | ^^</pre>
Laurent Heirendt's avatar
Laurent Heirendt committed
73
|:-----------------------------------|---------------------------|
Vilem Ded's avatar
Vilem Ded committed
74

Laurent Heirendt's avatar
Laurent Heirendt committed
75
For creating tables, follow the [Jekyll Spaceship documentation](https://github.com/jeffreytse/jekyll-spaceship).
Laurent Heirendt's avatar
Laurent Heirendt committed
76
77
78
This is an overview of basic Markdown features. For more in-build features, please see various online [documentation](https://www.markdownguide.org/basic-syntax/).

### Advanced formatting
Laurent Heirendt's avatar
Laurent Heirendt committed
79

Laurent Heirendt's avatar
Laurent Heirendt committed
80
81
82
83
84
85
Plain syntax is usually enough. But special requirements lead to development of many of so called ["flavored" markdown syntaxes](https://github.com/commonmark/commonmark-spec/wiki/markdown-flavors) implementing more formatting functionality such as linking different sections, highlighting blocks of code, table extensions, strikethroughs, ...

Another big advantage of Markdown is that it can contain HTML tags, which makes formatting very flexible.

## When to use markdown?

Laurent Heirendt's avatar
Laurent Heirendt committed
86
87
88
89
90
* **Documentation** - Markdown is a perfect solution for description of a data package, project folder, workflow or code repository. Using Markdown ensures that the description will be accessible to everyone even after decades while still nicely structured. Guide for writing a good README is not covered by this HowTo page but you can find plenty of resources online, e.g.:
  * [guide](https://data.research.cornell.edu/content/readme) from Cornell University, UK
  * [GitHub page](https://github.com/mhucka/readmine) for READMEs in a software repository
* **Blogging and tutorials** - structured document with chunks of code, pictures and results of the analyses can be easily converted to HTML format and posted on personal/team websites.
* **Notes and meeting minutes** - you can use following template for simple and nicely structured meeting notes:
Jacek Lebioda's avatar
Jacek Lebioda committed
91

Laurent Heirendt's avatar
Laurent Heirendt committed
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

| Markdown                           | Rendered Output           |
|:-----------------------------------|---------------------------|
|: <pre># DocTitle | # DocTitle
|: ^^### Attendees: |: ^^ <h3>Attendees:</h3>
|: ^^### Location: |: ^^ <h3>Location:</h3>
|: ^^## Objective / Agenda |: ^^ <h2>Objective / Agenda</h2>
|: ^^## Meeting Notes |: ^^ <h2>Meeting Notes</h2>
|: ^^  * first note |: ^^   * first note
|: ^^  * second note |: ^^   * second note
|: ^^  * ... |: ^^   * ...
|: ^^## Actions |: ^^ <h2>Actions</h2>
|: ^^- [ ] Josh, Alice and Cindy will do this. |: ^^ - [ ] Josh, Alice and Cindy will do this.
|: ^^- [x] Bob stops doing that. |: ^^ - [x] Bob stops doing that.
|: ^^- [ ] Will and Tom will take care of those </pre> |: ^^ - [ ] Will and Tom will take care of those </pre>
Laurent Heirendt's avatar
Laurent Heirendt committed
107

Laurent Heirendt's avatar
Laurent Heirendt committed
108
109
110
* **Analyses, reports and papers** - embedding [R markdown](https://rmarkdown.rstudio.com/) in an R project allows you to include executable code and related text in the very same document. This brings unprecedented level of consistency, shareability and reproducibility into the workflows.
* **Online discussion forums** - many scientific and non-scientific discussion forums and social networks support Markdown for formatting the content of messages (e.g. [StackOverflow](https://stackoverflow.com/editing-help), [GitHub](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax), Reddit or even Facebook)
* **Presentations** - variety of tools support Markdown-powered slide generation, e.g. [reveal.js](https://revealjs.com/#/), [HackerSlides](https://github.com/jacksingleton/hacker-slides) or [landslide](https://github.com/adamzap/landslide)
Laurent Heirendt's avatar
Laurent Heirendt committed
111
112
113

## Cases when Markdown is not easily applicable

Laurent Heirendt's avatar
Laurent Heirendt committed
114
115
116
* **Official documents** like legal agreements and project proposals could be in theory written in Markdown but it is not yet accepted by administrative processes.
* **Big structured tables** with multilevel headers or special formatting can be written in HTML editors and then pasted into your Markdown document.
* **Thesis writing** requires support of citation managers and additional formatting. This can be achieved but usually is conditioned by embedding Latex into your workflow.
Laurent Heirendt's avatar
Laurent Heirendt committed
117
118
119
120

## Editors
Markdown file can be written in any text editor. There are many editors supporting rendering and live preview, here are some of them:

Laurent Heirendt's avatar
Laurent Heirendt committed
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
* Freeware
  * Atom
  * Dillinger
  * Visual Studio Code
  * ghostwriter
  * Typora
  * HackMD
  * ...
* Payware:
  * iA Writer
  * SublimeText
  * ByWord
* Online
  * [GitHub pages](https://pages.github.com/)
  * [stackedit.io](stackedit.io)