Introduction

This page describes how to use markdown to edit texts such as reading notes, meeting notes, technical documentation or even scientific publications.

Common Mark is an attempt at standardizing markdown syntax. The common mark help page explains the syntax.

See also the publish page which mentions Latex tips and other editing ideas.

Images

Image

Pandoc convert to and from other file formats

Bash script for bulk conversion

Convert many markdown files with this bash script for pandoc

for mdfile in *.md; do
pdffile=${mdfile%.md}.pdf
echo $pdffile
done

Convert all docx documents to markdown in the current folder

for docxfile in *.docx; do
mdfile=${docxfile%.docx}.md
echo "converting $docxfile to $mdfile"
pandoc "$docxfile" -o "$mdfile"
done

Pandoc can convert to PDF, but not from PDF.

You can also create template files as explained in super user markdown to latex conversion with a custom preamble

See also the makefile for pandoc in the programming with bash / makefile section below.

Pandoc for research papers

How to use Pandoc to produce a research paper using the latex template of a journal to specify authorship in the way requested by the journal. Then the body of the article is written in Markdown.
Pandoc needs to be called with the --citeproc argument to generate a list of references from the citations. The bibliography file can be specified in the --bibliography argument.
```
pandoc article.md -o article.pdf --bibliography=article.bib --citeproc
```
- See also the YAML front matter section on bibliography. Even if the yaml front matter specifies a bibliography file, the --citeproc still needs to be called explicitly in order to process citations and generate a list of references.

Quarto

Goals:

The overarching goal of Quarto is to make the process of creating and collaborating on scientific and technical documents dramatically better. We hope to do this in several dimensions:

Create a writing and publishing environment with great integrated tools for technical content. We want to make authoring with embedded code, equations, figures, complex diagrams, interactive widgets, citations, cross references, and the myriad other special requirements of scientific discourse straightforward and productive for everyone.

Help authors take full advantage of the web as a connected, interactive platform for communications, while still providing the ability to create excellent printed output from the same document source. Researchers shouldn’t need to choose between LaTeX, MS Word, and HTML but rather be able to author documents that target all of them at the same time.

Make reproducible research and publications the norm rather than the exception. Reproducibility requires that the code and data required to create a manuscript are an integrated part of it. However, this isn’t often straightforward in practice—Quarto aims to make it easier to adopt a reproducible workflow than not.

Books that use quarto

Seen at https://quarto.org/docs/books/

Citations

To cite a reference in the format of “author (year)” from the bibliography, use:

@citationkey

To cite a reference inside brackets in the form of “(author year)”, place the citation key inside square brackets:

[@citationkey]

The bibliography is located at the end of the document by default.

Code chunks

Python and Jupyter

Need to set the extension as .qmd to enable execution of code chunks
Virtual environments https://quarto.org/docs/projects/virtual-environments.html
Debugging information
- verbose mode https://quarto.org/docs/troubleshooting/#verbose-mode
- Log files https://quarto.org/docs/troubleshooting/#log-files
  - Add this to the yaml block
    
    execute: debug: true
  - See log file in $HOME/.local/share/quarto/logs
- Using warnings to debug (it’s not ideal, but at least they get printed in the quarto output)
  
  import warnings warnings.warn(f”scenario_dir: {scenario_dir}: {scenario_dir.exists()}“)

Figures

Quarto documentation on figures https://quarto.org/docs/authoring/figures.html

Here is how to add a figure with caption and cross reference in quarto:

![An Elephant](elephant.png){#fig-elephant}

Example of a figure with caption and label, generated from python code. Note you would have to use single curly braces in the code chunk, these are only here so that this code chunk is not interpreted.


    >   ```{{python}}
    >   #| label: fig-plot
    >   #| fig-cap: "Plot 0, 1, 2, 3, 4"
    >   #| eval: false
    >   import matplotlib.pyplot as plt
    >   plt.plot([0,1,1,2,3,3,4], [0,1,3,2,1,3,4], "*c")
    >   plt.show()
    >   ```

Refer to the figures with an @ label:

see @fig-plot and @fig-elephant

Tables

Quarto tables

” The most commonly used markdown table is known as a pipe table. Pipe tables support specifying per column alignment as well as captions. For example:

| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12      | 12   |    12 |   12   |
| 123     | 123  |   123 |  123   |
| 1       | 1    |     1 |   1    |

“For tables produced by executable code cells, include a label with a tbl- prefix to make them cross-referenceable.”

“For markdown tables, add a caption below the table, then include a #tbl- label in braces at the end of the caption. For example:”

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: My Caption {#tbl-letters}

See @tbl-letters.

Yaml in quarto

Execution options https://quarto.org/docs/computations/execution-options.html

Option to not show code output

execute:
  echo: false

Text formating

Extra spaces

Add extra spaces

$~$

Seen at https://stackoverflow.com/a/60876153

Yaml front matter for styles

Bibliography

Custom yaml front matter for a markdown document that contains reading notes with citations. See also the vim.Rmd document on pandoc bibliographies.

---
title: Reading notes
author: Paul Rougieux
bibliography: /home/paul/rp/bioeconomy_papers/bibliography/jrc_ispra.bib
abstract: Reading notes at the JRC
header-includes: |
    \usepackage{fancyhdr}
    \pagestyle{fancy}
    \fancyhead[CO,CE]{Reading notes}
    \fancyfoot[CO,CE]{JRC}
    \fancyfoot[LE,RO]{\thepage}
---
\tableofcontents{}
...file content... this is probably not the way to do it    
\bibliography{../bibliography/jrc_ispra}
\bibliographystyle{apalike}

This is probably not the way to do it, the bibliography should be included in the pandoc call?

Pandoc requires citeproc to process the bibliography, install it with

sudo apt install pandoc-citeproc

Explicitly call the --citeproc argument to generate a list of references from the citations

pandoc article.md -o article.pdf --citeproc

Paper size and margins

Change the margin to 0.5 cm

---
title: "Songs of freedom"
author: "Bob Marley"
geometry: margin=0.5cm
---

A4 paper

---
title: LETTERA
papersize: A4
---

Page numbers

Adding headers and footers to pandoc suggests using:

---
title: Test
author: Author Name
header-includes: |
    \usepackage{fancyhdr}
    \pagestyle{fancy}
    \fancyhead[CO,CE]{This is fancy}
    \fancyfoot[CO,CE]{So is this}
    \fancyfoot[LE,RO]{\thepage}
abstract: This is a pandoc test . . . 
---

Table of content

Add a table of content at the beginning of the document

---
title: "Work plan"
geometry: margin=2cm
toc: yes
---

When specified in the yaml front matter only, the table of content appears in pdf output but not in html output. This may be due to a difference in the latex and html templates? Display the content of the latex and html templates

pandoc -D latex
pandoc -D html

However calling the –toc argument does create a table of content in the html file:

pandoc -s --toc notes.md -o notes.html

Two column layout and class options

The openany option for the book document class, allows opening a chapter on any page left or right, otherwise the book class forces chapter opening on the left page only and inserts a blank page.

---
title: "Songs"
geometry: margin=0.5cm
documentclass: book
classoption:
- twocolumn
- openany
---

Flavours of markdown

Common Mark

Stack Overflow

The Stack Exchange network used to have a custom flavoured markdown, but they switched to common mark in 2020 We’re switching to CommonMark

“Another reason is that this reduces some of the maintenance burdens of our development teams. Instead of maintaining two distinct Markdown renderers, we can now pick something off the shelf and use that instead. With markdig and markdown-it we’ve found two reputable libraries that are beating our own implementations when it comes to performance and functionality. Both are great pieces of software that we’re more than happy to use in our product.”
Stack Overflow markdown editing help.

Github flavoured markdown

How to add a collapsible section
Click me
```
  plot(iris)
```

Rules: Have an empty line after the </summary> tag or markdown/code blocks will not render. Have an empty line after each </details> tag if you have multiple collapsible sections.

Gitlab flavoured markdown

https://docs.gitlab.com/ee/user/markdown.html#task-lists

“To create a task list, follow the format of an ordered or unordered list”

- [x] Completed task
- [~] Inapplicable task
- [ ] Incomplete task
  - [x] Sub-task 1
  - [~] Sub-task 2
  - [ ] Sub-task 3

1. [x] Completed task
1. [~] Inapplicable task
1. [ ] Incomplete task
   1. [x] Sub-task 1
   1. [~] Sub-task 2
   1. [ ] Sub-task 3

Markdown