--- 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 ![h:250](assets/logo.png) **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](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 for slides 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 Now you can take a look of the Markdown code of these **current slides** ! --- # Markdown for a paper ? ## Scientific manuscript for submision ```bash pandoc -d article.yaml ``` Here, we use a `yaml` file to write all the pandoc options (passed with `-d`) ## Scientific manuscript ```bash pandoc -d article_nice.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**