insights

Using Markdown for Note Taking

March 17, 2020

Why Markdown?

If you’re making technical notes or documents, Markdown is super easy when working with formatted code, images and links. It can easily be converted to Word, HTML or PDF.

Nowadays it’s used by GitHub and lots of others popular tools.

Using Visual Studio Code

VS Code has all the Markdown syntax highlighting, and can preview the document using the preview button, highlighted below. Plus it has plugins for linting, pasting images directly in, timestamps and much more.

Other text editors are available, but let’s not start that debate.

Converting Markdown Using Pandoc

Here we’ve used VS Code and WSL, which works nicely. Pandoc can be installed on Macs with Brew.

First install pandoc and a pdf renderer:

sudo apt-get install texlive pandoc

Creating PDF Files

To convert from Markdown to PDF you do this (-V allows specification of variables such as margins):

pandoc --latex-engine=xelatex -V geometry:margin=3cm -s -o doc.pdf test.md

Creating docx Files

Converting to Word docx format is the same. It’s possible to also take in a template document, using the -t argument, which is used to apply styles to the finished document.

pandoc --latex-engine=xelatex -V geometry:margin=3cm -s -o doc.docx input.md

And before we get into writing Markdown itself, here’s a little bash script to wrap Pandoc:

#!/bin/bash

# check it exists
if test -f "$1"; then
    echo "Converting $1"
else
   echo "Can't find \"$1\""
   exit -1
fi

# get the filename sans extension
filename=$(basename -- "$1")
filename="${filename%.*}"

# create the document
pandoc --latex-engine=xelatex -V geometry:margin=3cm -s -o $filename.docx $1

# Done
echo "Converted to $filename.docx"

Markdown Cheat Sheet

The following examples of Markdown formatting are largely taken from this GitHub post.

Headings

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

 

Text Formatting

Emphasis, aka italics, with *asterisks* or _underscores_.
Strong emphasis, aka bold, with **asterisks** or __underscores__.
Combined emphasis with **asterisks and _underscores_**.
Strikethrough uses two tildes. ~~Scratch this.~~

 

Timestamps

Timestamps There are VS Code plugins for adding timestamps, e.g.: 2020-03-13T10:24:30.403Z.

 

Quotes

## Quotes
> Blockquotes are very handy in email to emulate reply text.
> This line is part of the same quote.

Quote break.

This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.

Links

# Links
[I'm an inline-style link](https://www.google.com)
[I'm an inline-style link with title](https://www.google.com "Google's Homepage")
[I'm a relative reference to a repository file](../blob/master/LICENSE)

Images

See this VS Code plugin for pasting images.

# Images You can use [this VS Code plugin](https://marketplace.visualstudio.com/items?itemName=Liu-Yongle.paste-image-to-markdown) to paste images into Markdown. It saves them to the same location as the markdown file. ![Here's an example image](2020-03-13-09-49-17.png)

Syntax Highlighted Code

# Code
```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```

```python
s = "Python syntax highlighting"
print s
```

```
No language indicated, so no syntax highlighting. 
But let's throw in a <b>tag</b>.
```

Tables

# Tables
| Tables | Are | Cool |
| ------------- |:-------------:| -----:|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |

For our latest research, and for links and comments on other research, follow our Lab on Twitter.

Cyber Lab