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

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

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

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

VS Code in WSL

Open a Powershell terminal in Administrator mode and do

wsl --update

Open the Ubuntu terminal and do

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

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

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 you must install Chrome, Chromium or Edge

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 ?

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 ?

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

https://github.com/MartinHeroux/latex-paper-template

https://github.com/MartinHeroux/markdown-latex-template

MarkDown.md 7.9 KB History Raw