Markdown and applications

https://forge.uclouvain.be/elic/learning.git

Pierre-Yves Barriat
ACELI Training Sessions March 25th, 2025

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

25/03/2025 | Markdown and applications | PY Barriat

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 ( LaTeX)

  • Markdown is everywhere : Reddit, GitHub, readme, etc

25/03/2025 | Markdown and applications | PY Barriat

Live Demo

Several online Markdown editors to try writing in Markdown

For example, try StackEdit

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

25/03/2025 | Markdown and applications | PY Barriat

Prerequisites

25/03/2025 | Markdown and applications | PY Barriat

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 in the learning-git folder in:
https://forge.uclouvain.be/elic/learning.git

25/03/2025 | Markdown and applications | PY Barriat

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

cd ; git clone https://forge.uclouvain.be/elic/learning.git
cd learning/learning-markdown/
chmod 755 assets/install_all.bash
./assets/install_all.bash
exit
25/03/2025 | Markdown and applications | PY Barriat

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

25/03/2025 | Markdown and applications | PY Barriat

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

25/03/2025 | Markdown and applications | PY Barriat

VS Code nice extensions

Open VS Code and install the following extensions

  • Markdown All in One : v3.6.3 - Yu Zhang
  • Marp for VS Code : v3.1.1 - Marp team

And maybe :

  • Markdown Preview Enhanced : v0.8.18 - Yiyi Wang
  • Markdownlint : v0.59.0 - David Anson
  • Pandoc Markdown : v0.1.2 - rsolano
  • Excel to Markdown table : v1.3.0 - Sebastian Holmqvist
25/03/2025 | Markdown and applications | PY Barriat

Markdown Basic Syntax

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

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

cd ~/learning/learning-markdown/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"
25/03/2025 | Markdown and applications | PY Barriat

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
25/03/2025 | Markdown and applications | PY Barriat

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.

25/03/2025 | Markdown and applications | PY Barriat

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

25/03/2025 | Markdown and applications | PY Barriat

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 --lua-filter assets/columns.lua --listings

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
25/03/2025 | Markdown and applications | PY Barriat

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 !

25/03/2025 | Markdown and applications | PY Barriat

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
25/03/2025 | Markdown and applications | PY Barriat

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

25/03/2025 | Markdown and applications | PY Barriat

  • 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

25/03/2025 | Markdown and applications | PY Barriat