---
marp: true
title: Markdown and applications
author: P.Y. Barriat
description: Markdown and applications
backgroundImage: url('assets/back.png')
_backgroundImage: url('assets/garde.png')
footer: 02/06/2023 | Markdown and applications | PY Barriat
_footer: ""
paginate: true
_paginate: false
#math: true
---

Markdown and applications<!--fit-->
===

https://gogs.elic.ucl.ac.be/pbarriat/learning-markdown

![h:280](assets/logo.png)

**Pierre-Yves Barriat**
ELIC Training Sessions `June 13th, 2023`

---

# What is Markdown ?

Lightweight **markup language** (a *text-encoding system*)

> "Set of symbols inserted in a text document to control its structure, formatting, or the relationship between its parts."

Others markup languages: HTML, LaTeX, etc

Created in 2004, **Markdown** is now one of the world’s most popular markup languages

Markdown is different than using a `WYSIWYG`

---

# Why Markdown ?

- Markdown is for **everything**: websites, documents, notes, books, presentations, email messages, technical documentation

- Markdown is **portable** 
  > MS Word locks your content into a proprietary file format

- Markdown is platform **independent**

- Markdown is **simple** and future proof
  > so easy to learn ( $\neq$ LaTeX)

- Markdown is **everywhere** : Reddit, GitHub, readme, etc

---

# Live Demo

Several online Markdown editors to try writing in Markdown

For example, try [Dillinger](https://dillinger.io/)

After you've become familiar with Markdown, you may want to use a Markdown application that can be installed on your computer

---

# Prerequisites

- text editor : [Visual Studio Code](https://code.visualstudio.com/download)

- universal document converter : [Pandoc](https://pandoc.org/installing.html)

- TeX distribution : [LaTeX](https://www.latex-project.org/)

- Markdown presentation ecosystem : [Marp](https://marp.app/)

---

## Visual Studio Code

VSC is one of the most popular and powerful text editors used by software engineers today 
> free and available for [macOS](https://www.youtube.com/watch?v=8CJXB4Nu1wo), [Windows](https://www.youtube.com/watch?v=AdeWO-n9O2Q) and [Linux](https://code.visualstudio.com/download)

### You didn't already install VS Code ?

Take a look here
https://gogs.elic.ucl.ac.be/pbarriat/learning-vscode

---

### VS Code in WSL

Open a **Powershell terminal** in **Administrator mode** and do

```sh
wsl --update
```

Open the **Ubuntu terminal** and do

```bash
sudo apt update
sudo apt upgrade
sudo apt install gedit -y
sudo apt install chromium-browser -y
```

---

### VS Code in Ubuntu

Open the **terminal** and do

```bash
sudo apt update
sudo apt upgrade
sudo apt install chromium-browser -y
```

### VS Code in any case

Open VS Code and install the following extensions

- `Markdown All in One`
- `Marp`
- `Pandoc Markdown`

---

## Pandoc

Pandoc is a library for converting from one markup format to another, and a command-line tool that uses this library.
> free and available for macOS, Windows, and Linux
> - [Pandoc](https://github.com/jgm/pandoc/releases)
> - [Pandoc-crossref](https://github.com/lierdakil/pandoc-crossref/releases)

```bash
cd
wget https://github.com/jgm/pandoc/releases/download/3.1.2/pandoc-3.1.2-linux-amd64.tar.gz
wget https://github.com/lierdakil/pandoc-crossref/releases/download/v0.3.16.0/pandoc-crossref-Linux.tar.xz
tar xzf pandoc-3.1.2-linux-amd64.tar.gz
tar -xf pandoc-crossref-Linux.tar.xz
mv pandoc-3.1.2/* .
mv pandoc-crossref bin
mv pandoc-crossref.1 share/man/man1
echo "export PATH=\$PATH:\$HOME/bin" >> .bashrc
echo "export MANPATH=\$MANPATH:\$HOME/share" >> .bashrc
rm -rf pandoc-3.1.2 pandoc-3.1.2-linux-amd64.tar.gz pandoc-crossref-Linux.tar.xz
```

---

## TeX distribution

**LaTeX** is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation.
> free and available for [macOS](https://www.tug.org/mactex/), [Windows](https://miktex.org/download), and Linux

```bash
sudo apt install -y texlive-latex-base \
                 texlive-latex-recommended \
                 texlive-fonts-recommended \
                 texlive-latex-extra \
                 texlive-fonts-extra \
                 texlive-xetex \
                 texlive-lang-french \
                 texlive-latex-extra
```

---

## Marp

Marp (MarkDown slides extension) can convert **Marp Markdown** files into static HTML/CSS, PDF, PowerPoint document, and image(s) easily

Download and install marp-cli (a **CLI** interface for Marp) from the standalone binaries
> free and [available](https://github.com/marp-team/marp-cli/releases/) for macOS, Windows and Linux
> you must install Chrome, Chromium or Edge

```bash
cd
wget https://github.com/marp-team/marp-cli/releases/download/v2.5.0/marp-cli-v2.5.0-linux.tar.gz
tar xzf marp-cli-v2.5.0-linux.tar.gz
mv marp bin ; rm -f marp-cli-v2.5.0-linux.tar.gz
```

---

## VS Code nice extensions

- `Remote - SSH` : lets you use any remote machine with a SSH server
- `Tabnine` : code faster with AI code completions
- `Regex Previewer` : shows the current regular expression's matches
- `Markdown Preview Enhanced `
- `Markdownlint`

And :

- `Modern Fortran`

---

# Markdown Basic Syntax

https://www.markdownguide.org/basic-syntax/

## My first example: README.md on a Git web server

https://gogs.elic.ucl.ac.be/pbarriat/learning-markdown/src/master/example

### How to convert it ?

```bash
pandoc -s README.md -o README.pdf

pandoc -s README.md -o README.docx

pandoc -s README.md -o README.html --metadata title="README for EcEARTH"
```

---

### How to custom the target style ?

Using HTML template (html file and/or css)

```bash
pandoc -s README.md -o README.html --metadata title="README for EcEARTH" \
    --template=html_templates/easy_template.html --toc
```

> don't forget to add `--toc` if you want a table of contents

> you can also use the **VS Code Pandoc extension** to export/preview in HTML

Using Latex template (latex file)

```bash
pandoc -s README.md -o README.pdf --template tex_templates/eisvogel
```

---

## My second example: a letter

Using my **UCLouvain letter** template (latex file)

```bash
pandoc -s letter.md -o letter.pdf --pdf-engine=xelatex --template tex_templates/letter
```

> **pdflatex** and **xelatex** are two implementations for the same purpose.
> One of the main differences is that **xelatex** has better support for fonts: in particular you can use system fonts instead of only TeX fonts. It also has better support for non-latin character encodings.

---

# Markdown Extended Syntax

https://www.markdownguide.org/extended-syntax/

## A scientific report

```bash
pandoc -s report.md -o report.html --webtex -H html_templates/report.css \
       --bibliography assets/MyLib.bib --citeproc

pandoc -s report.md -o report.pdf --template tex_templates/eisvogel \
       --bibliography assets/MyLib.bib --citeproc
```

> don't forget to add `--webtex` if you want TeX formula in HTML

> here we integrate a TeX bibliography

> don't forget to add `--citeproc` if you want a list of references

---

## Extended syntax example

```bash
pandoc -s advanced.md -o advanced.html --webtex -H html_templates/report.css --citeproc

pandoc -s advanced.md -o advanced.pdf --template tex_templates/eisvogel --citeproc
```

Compare the HTML ouput and the PDF output !

Some features are rendered only for PDF or HTML :

- depends on **CSS** or **HTML** template
- depends on **LaTeX** template

---

# Markdown slides: Marp

Replace `pandoc` command with `marp`

```bash
marp slides.md -o slides.pdf

marp --bespoke.progress slides.md -o slides.html
```

> don't forget to add `--bespoke.progress` if you want a progress status

---

# A bigger document ? a report maybe ?

---

# My last example: a scientific paper !

#marp --allow-local-files --theme tum.css git_elic.md -o git_elic.pdf
#marp --template bespoke --bespoke.progress --allow-local-files --theme tum.css git_elic.md -o git_elic.html

https://jaantollander.com/post/scientific-writing-with-markdown/

https://curvenote.com/blog/writing-a-scientific-paper-faster-myst-markdown

https://github.com/MartinHeroux/pandoc_article_template

https://phd.row1.ca/phd
