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
https://gogs.elic.ucl.ac.be/pbarriat/learning-markdown
Pierre-Yves Barriat
ELIC Training Sessions June 14th, 2023
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
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
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
text editor : Visual Studio Code
universal document converter : Pandoc
TeX distribution : LaTeX
Markdown presentation ecosystem : Marp
VSC is one of the most popular and powerful text editors used by software engineers today
Take a look here https://gogs.elic.ucl.ac.be/pbarriat/learning-vscode
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
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
LaTeX is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation.
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 (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
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
Open VS Code and install the following extensions
Markdown All in One
: v3.5.1 - Yu ZhangMarp for VS Code
: v2.6.0 - Marp teamAnd maybe :
Markdown Preview Enhanced
: v0.6.8 - Yiyi WangMarkdownlint
: v0.50.0 - David AnsonPandoc Markdown
: v0.1.2 - rsolanoExcel to Markdown table
: v1.3.0 - Sebastian Holmqvisthttps://www.markdownguide.org/basic-syntax/
https://gogs.elic.ucl.ac.be/pbarriat/learning-markdown/src/master/example
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"
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 contentsyou 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
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.
https://www.markdownguide.org/extended-syntax/
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 HTMLhere we integrate a TeX bibliography
don't forget to add
--citeproc
if you want a list of references
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 :
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 !
pandoc -d article.yaml
Here, we use a yaml
file to write all the pandoc options (passed with -d
)
pandoc -d nice_article.yaml
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