This document presents a brief overview of the Markdown syntax and builds on a presentation from the Github team and blog post from Archer Reilly.
# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag
*This text will be italic*
_This will also be italic_
**This text will be bold**
__This will also be bold__
_You **can** combine them_
- Item 1
- Item 2
- Item 2a
- Item 2b
1. Item 1
2. Item 2
3. Item 3
1. Item 3a
2. Item 3b
Format: 
http://github.com - automatic!
[GitHub](http://github.com)
As Kanye West said:
> We're living the future so
> the present is our past.
To print some text with python, you should use the `print()` function.
```
print("Hello world!")
```
Math formulas are easy to write using Markdown, either using the inline mode or the displayed formulas mode. With the inline mode, formulas are inlined in the current paragraph whereas with the displayed mode, they appear as centered and emphasized.
The formatting generally slightly differs in both cases since, to display nicely on a single line, it is generally required to pack them a bit more than when they are emphasized.
To write formulas using the inline mode, they should be surrounded by a single $ (as a consequence, whenever you need to use the original dollar symbol, you should prefix it with a backslash: \$). To write formulas using the displayed mode, they should be surrounded by a $$. Here are a few examples:
This expression $\sum_{i=1}^n X_i$ is inlined.
This expression \(\sum_{i=1}^n X_i\) is inlined.
This expression is emphasized:
$$\sum_{i=1}^n X_i$$
This expression is emphasized:
\[\sum_{i=1}^n X_i\]
In the rest of this section we present a brief selection of common symbols and commands. Actually, almost any classical LaTeX command can used as such in Markdown, provided it is surrounded by a $. For more complete examples, please have a look at these ces examples by James H. Steiger.
| Symbol | Command |
|---|---|
| \(\alpha\) | $\alpha$ |
| \(\beta\) | $\beta$ |
| \(\gamma\) | $\gamma$ |
| \(\Gamma\) | $\Gamma$ |
| \(\pi\) | $\pi$ |
| Symbol | Command |
|---|---|
| \(\cos\) | $\cos$ |
| \(\sin\) | $\sin$ |
| \(\lim\) | $\lim$ |
| \(\exp\) | $\exp$ |
| \(\to\) | $\to$ |
| \(\in\) | $\in$ |
| \(\forall\) | $\forall$ |
| \(\exists\) | $\exists$ |
| \(\equiv\) | $\equiv$ |
| \(\sim\) | $\sim$ |
| \(\approx\) | $\approx$ |
| \(\times\) | $\times$ |
| \(\le\) | $\le$ |
| \(\ge\) | $\ge$ |
| Symbol | Command |
|---|---|
| \(k_{n+1}\) | $k_{n+1}$ |
| \(n^2\) | $n^2$ |
| \(k_n^2\) | $k_n^2$ |
| Symbol | Command |
|---|---|
| \(\frac{4z^3}{16}\) | $\frac{4z^3}{16}$ |
| \(\frac{n!}{k!(n-k)!}\) | $\frac{n!}{k!(n-k)!}$ |
| \(\binom{n}{k}\) | $\binom{n}{k}$ |
| \(\frac{\frac{x}{1}}{x - y}\) | $\frac{\frac{x}{1}}{x - y}$ |
| \(^3/_7\) | $^3/_7$ |
| \(\sqrt{k}\) | $\sqrt{k}$ |
| \(\sqrt[n]{k}\) | $\sqrt[n]{k}$ |
| Symbol | Command |
|---|---|
| \(\sum_{i=1}^{10} t_i\) | $\sum_{i=1}^{10} t_i$ |
| \(\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x\) | $\int_0^\infty \mathrm{e}^{-x}\,\mathrm{d}x$ |
| Symbol | Command |
|---|---|
| \(\hat{a}\) | $\hat{a}$ |
| \(\bar{a}\) | $\bar{a}$ |
| \(\dot{a}\) | $\dot{a}$ |
| \(\ddot{a}\) | $\ddot{a}$ |
| \(\overrightarrow{AB}\) | $\overrightarrow{AB}$ |
markdownFirst of all, to know more about markdown and its extensions, you may want to read:
markdown syntax.As we explain in the video, github and gitlab allow you to easily edit mardown documents and to render them in html. This is quite convenient but may be a bit cumbersome for a daily use. You may prefer to edit these documents with a real editor and later to export them in whichever format you may like (html, pdf, docx, epub, etc). There are a few editors specifically designed for markdown (see for example the Editors page of the pandoc website) but we rather advise you to use a general-purpose editor that is capable of handling the markdown syntax. A few ones were mentioned in the beginning of the video and additional information are available in the "Quelques éditeurs adaptés à l'édition Markdown" section of Jean-Daniel Bonjour's tutorial.
To convert markdown in an "arbitrary" other format, the best solution today is Pandoc, a software developed by John MacFarlane, a philosopher from de Berkeley, and whose main page is on github. J.-D. Bonjour's tutorial provides many explanations on how to install and use pandoc in the Utilisation du convertisseur Pandoc section. pandoc is written in Haskell and may be a bit cumbersome to install. Therefore, we provide here a few alternative solutions:
markdown files into pdf files without having to install anything on your computer.markdown syntax and converters markdown → html / LaTeX written in C and JavaScript (https://github.com/CommonMark/CommonMark).markdown, a markdown → html converter written in perl.markdown extension that provides its own markdown → html converter written in C.python-based server that allows you to convert on the fly markdown documents and to preview them with your favorite browser (this is quite useful to avoid useless commits just for the sake of previewing when using github ou gitlab).The pdf conversion always relies on LaTeX, which requires a full-fledged and running LaTeX installation on your computer.
In the demo, we show how to generate a docx from a markdown document with Pandoc and we explain that it is then possible to use a word processor like LibreOffice to edit the resulting file. Obviously the modifications will not be back-propagated to the original markdown document. You may however want to use Pandoc again to convert your new docx document to a new markdown document.
Another common strategy consists in doing most of the editing of an article/report in Markdown and to export it into a docx (or LaTeX) only in the end so as to prepare it for a camera-ready version with a standard word processing environment (or a LaTeX editor).
The resources listed under the Sustain section of "The Programming Historian" are all relevant for Module 1 (in particular the tutorial on Git/GitHub).