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: 14/06/2023 | Markdown and applications | PY Barriat _footer: "" paginate: true _paginate: false

#math: true

Markdown and applications

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

Pierre-Yves Barriat ELIC Training Sessions June 14th, 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

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
universal document converter : Pandoc
TeX distribution : LaTeX
Markdown presentation ecosystem : Marp

Visual Studio Code

VSC is one of the most popular and powerful text editors used by software engineers today

free and available for macOS, Windows and Linux

You didn't already install VS Code ?

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

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

Pandoc-crossref

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, Windows, and Linux

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 for macOS, Windows and Linux

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

You must install Chrome, Chromium or Edge

True Ubuntu, install chromium-browser

sudo apt install chromium-browser -y

Ubuntu with WSL, add ppa for google-chrome and install it

wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmour -o /usr/share/keyrings/google_linux_signing_key.gpg
sudo sh -c 'echo "deb [arch=amd64 signed-by=/usr/share/keyrings/google_linux_signing_key.gpg] http://dl.google.com/linux/chrome/deb/ stable main" > /etc/apt/sources.list.d/google.list'
sudo apt update
sudo apt install google-chrome-stable

In WSL, snapd is not available by default and chromium-browser needs it

VS Code nice extensions

Open VS Code and install the following extensions

Markdown All in One : v3.5.1 - Yu Zhang
Marp for VS Code : v2.6.0 - Marp team

And maybe :

Markdown Preview Enhanced : v0.6.8 - Yiyi Wang
Markdownlint : v0.50.0 - David Anson
Pandoc Markdown : v0.1.2 - rsolano
Excel to Markdown table : v1.3.0 - Sebastian Holmqvist

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 ?

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)

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)

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

My second example: a letter

Using my UCLouvain letter template (latex file)

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

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

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 for slides

Replace pandoc command with marp

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

Now you can take a look of the Markdown code of these current slides !

Markdown for a paper ?

Scientific manuscript for submision

pandoc -d article.yaml

Here, we use a yaml file to write all the pandoc options (passed with -d)

Scientific manuscript

pandoc -d nice_article.yaml

Conclusion

You can learn Markdown very quickly
Markdown is directly human-readable so it's easy to share with people who don't have Markdown processor installed
Installing a Markdown processor is easy
Markdown is easily convertible to HTML

best choice for documents to be published both on the web and as printed text
You can create high-quality scientific documents

Markdown is also good for quick note taking

you can effortlessly apply text formattings to, e.g., highlight parts in your notes or to create formatted lists
The layout can be controlled by settings within the raw documents or you simply keep the default settings
The design of your document guarantees a consistent and uniform layout

font types and sizes of text and headings, tables and directories, footnotes, page numbering, line spacing and borders, etc
The file formats for writing the raw content in both languages (*.md, *.tex) are designated as open format

MarkDown.md 9.0 KB History Raw