10.07 Markown

Markdown is our preferred open-data format for the documentation (website), for writing papers and theses, managing knowledge, and creating slides. It is platform-independent, integrates well with git, and can easily be converted to other formats (e.g., PDF, HTML, DOCX) using Pandoc.

Table of contents

Guidelines

  • Each sentence should be in a new line (to ensure that the git diff is readable). To create a paragraph, add an empty line. This makes the history more readable and merging easier (see semantic line breaks).

Documentation 

# Links that open in a separate window:
[name that displayed](https://website.com){: target="_blank"}

# References
<div class="references">
  <p>Author, A. A. (Year). Title of work: Capital letter also for subtitle. Publisher.</p>
</div>

Graphs can be included as Mermaid diagrams:

Mermaid live editor

Papers, theses and books

A very useful possibility is to include comments throughout the markdown document:

<!-- Comment can be used to add further explanations, links to references/resources, or to keep parts of the paper that were shortened -->

Papers are cited using the citation keys in the references.bib file and the citation syntax @Webster2002 or [@Webster2002]. Groups of in-text citations should be sorted alphabetically (especially if a prefix is used), i.e., use [e.g., @Bacharach1989; @Gregor2006a] instead of [e.g., @Gregor2006a; @Bacharach1989].

The syntax is based on the citation syntax (see CSL).

To add papers that are cited in the figure to the reference section, include the following in the YAML header of paper.md:

---
title: ...
author: ...
nocite: |
  @citation_key
---

Further Information on the citation syntax is available in the pandoc manual.

Figures can be included as follows and referred to as @fig:distribution. Further information on pandoc-crossref is available online.

![Figure Caption](figures/figure.jpg){#fig:distribution width=300px}

To ensure compatibility with pandoc word and latex conversion, figures should be included as jpg/png. For the final versions, vector graphics (PDF, EMF) should be included for Latex/Word respectively.

Formulas can be included as follows:

$$ P_i(x) = \sum_i a_i x^i $$ {#eq:eqn1}

Tables can be created with GridTables (which is displayed in PDF and Word documents):

+---------------------+----------+
| Property            | Earth    |
+=============+=======+==========+
|             | min   | -89.2 °C |
| Temperature +-------+----------+
| 1961-1990   | mean  | 14 °C    |
|             +-------+----------+
|             | max   | 56.7 °C  |
+-------------+-------+----------+

Table: Findings {#tbl:findings}

We show the findings in @tbl:findings.

Markdown table editor

Footnotes:

Text with a footnote [^1].

  [^1]: Example footnote.

Information on referenes and citations is in editing-markdown-paper section.

Books: bookdown project.

Slides

  • Open source Markdown-based presentation tool
  • Creating slides with text, images, code blocks, diagrams, …
  • Exporting Presentations to many formats (HTML, PDF, …)
  • Speaker notes and presenter view during presentations
  • CSS styling for customization
  • Good integration with Git
  • Template is available here

Centered text:

<!-- _class: centered -->

Format references:

<style scoped>
p {
    padding-left: 36px;
    text-indent: -36px;
}
</style>

# References

Weritz, P. (2022). Hey leaders, It’s time to train the workforce: Critical skills in the digital workplace. *Administrative Sciences*, 12(3), 94. doi: [10.3390/admsci12030094](https://doi.org/10.3390/admsci12030094).

Exercise sheets

Jupyter notebooks are useful to create exercise sheets, combinint Markdown with Python or R.

Knowledge management

For knowledge management tasks, we use Obsidian.

  • Each note (paper summary or concept) should be an a separate, atomic note (see 1, 2.
  • Paper summaries should have the filename citation_key.md, with the citation_key corresponding to the ID in a BibTex file.

Resources