Wissenschaftliches Publizieren mit Quarto

Alexander Weisse (MPIM Bonn)

Evolution

Markdown

Vorteile

  • Universelles, strukturiertes Plain-Text-Format, erfunden als HTML-Ersatz
  • Leicht zu erlernen, schnell zu schreiben, direkt lesbar
  • Weit verbreitet, d.h. viele Tools können es verarbeiten
  • Hervoragend versionierbar, alterungsbeständig

Was fehlte?

  • Zitate und Literaturverzeichnisse, Mathematik
  • Erweiterungsmöglichkeiten
  • Konvertierung in andere Formate als HTML

Pandoc

Vorteile

  • Universeller Super-Konverter zwischen aktuell 48 Input- und 68 Output-Formaten (Markdown, Wikis, Office, \text{\LaTeX}, Typst, PDF, …)
  • Erweiterung von Markdown um Features für wissenschaftliche Dokumente: Zitate, Literaturverzeichnisse und Mathematik
  • Hervoragendes Tool für Artikel, Präsentationen und einfache Webseiten

Was fehlte?

  • Konvertierung in andere Formate erfordert etwas Handarbeit (CLI, Makefiles, …)
  • Wenig Automatismen und Werkzeuge für Webseiten (z.B. Menüs, Templates)
  • Keine Ausführung von eingebettetem Programm-Code (wie bei Jupyter-Notebooks)

Quarto

  • Bündelt Pandoc mit anderen Tools zu einem open-source scientific and technical publishing system
  • Eingebetteter Python, R, Julia, und Observable JS Code kann ausgeführt werden
  • Konvertiert Markdown (.qmd) oder Jupyter-Notebooks in Artikel, Präsentationen, Bücher, Webseiten, etc. als HTML, PDF, ePub, Office.
  • Enthält ansprechende Templates
  • Plugins für Emacs, Neovim, RStudio, VS Code, …

Grundlagen

Diese Präsentation (.qmd)

---
title: "Wissenschaftliches Publizieren mit *Quarto*"
subtitle: "![](images/talk-qr.svg)"
author: "Alexander Weisse (MPIM Bonn)"
lang: de
format: revealjs
bibliography: references.bib
html-math-method: katex
---
# Evolution

## [Markdown](https://daringfireball.net/projects/markdown/)

::: { .callout-tip }
### Vorteile
- Universelles, strukturiertes Plain-Text-Format, erfunden als
  HTML-Ersatz
- Leicht zu erlernen, schnell zu schreiben, direkt lesbar
- Weit verbreitet, d.h. viele Tools können es verarbeiten
- Hervoragend versionierbar, alterungsbeständig
:::

  • Live-Vorschau während des Editierens

    quarto preview quarto.qmd

  • Rendering nach Reveal JS Präsentation (HTML)

    quarto render quarto.qmd

  • Rendering nach Office

    quarto render quarto.qmd --to docx
  • Editieren mit Preview in VS Code
  • Rendern mit Gitlab CI/CD und Publizieren nach Gitlab Pages
# image: ghcr.io/quarto-dev/quarto:1.8.24
image: debian:latest

pages:
  script:
    - apt update
    - apt -y --install-recommends install make curl jq unzip jupyter python3-matplotlib
    - curl -sL -o quarto.deb `curl -s https://api.github.com/repos/quarto-dev/quarto-cli/releases/tags/v1.8.24 | jq -r 'first(.assets[]|select(.name|endswith("amd64.deb"))|.browser_download_url)'`
    - dpkg -i quarto.deb
    - quarto check
    - quarto render quarto.qmd --output-dir public -o index.html
  artifacts:
    paths:
      - public
  only:
    - main

Wissenschaftliche Dokumente

Mathematik

  • Pandoc ergänzt Markdown um Formeln und mathematische Notation auf Basis von \text{\TeX}
  • Quarto erlaubt Labels und Quer-Verweise
Die Riemannsche $\zeta$-Funktion, ist für $\text{Re}(s)>1$ definiert als 
$$
\zeta(s) = \sum_{n=1}^{\infty} \frac{1}{n^s}
$$ {#eq-zeta}
und kann nach $\mathbb{C}$ meromorph fortgesetzt werden.

Die Riemannsche \zeta-Funktion, ist für \text{Re}(s)>1 definiert als \zeta(s) = \sum_{n=1}^{\infty} \frac{1}{n^s} \tag{1} und kann nach \mathbb{C} meromorph fortgesetzt werden.

Code Ausführung

Quarto erlaubt die Ausführung von eingebetteten Programmen (Python, Julia, R, Observable JS)

```{python}
#| label: fig-zeta
#| fig-cap: "Riemann-$\\zeta$ aus @eq-zeta entlang der kritischen Linie."
import numpy as np
import matplotlib.pyplot as plt
from mpmath import zeta, zetazero

r = np.arange(0, 26, 0.01)
zeta = [ zeta(0.5 + y*1j) for y in r ]
fig, ax = plt.subplots()
ax.plot(r, [ z.real for z in zeta ], label="Re($\zeta$)")
ax.plot(r, [ z.imag for z in zeta ], label="Im($\zeta$)")
ax.scatter([ zetazero(k).imag for k in [1,2,3]], [0,0,0], color="green")
ax.grid(True)
ax.legend(loc="upper left", shadow=True)
plt.show()
```

Abbildung 1 zeigt eine Grafik, die mit Python erzeugt und in das Dokument eingebettet wurde.

Dies fördert die Reproduzierbarkeit von Ergebnissen.

Abbildung 1: Riemann-\zeta aus Gleichung 1 entlang der kritischen Linie.

Zitate und Literaturverzeichnisse

Pandoc erweitert Markdown um eine Syntax für Zitate und Tools zur Erzeugung von Literaturverzeichnissen:

  • Mit [@key] werden Referenzen aus einer Literaturdatenbank zitiert.
  • Literaturdatenbanken können als .bib, .json, .yaml oder RIS vorliegen.
  • Zur Formatierung wird die Citation Style Language (CSL) verwendet.

Quer-Verweise

Quarto führt zusätzlich Verweise auf Abbildungen, Tabellen und Gleichungen ein (@fig-xyz, @tbl-xyz und @eq-xyz)

Beispiel

Auch Alan Turing beschäftigte sich mehrfach mit der Funktion
$\zeta(s)$ aus @eq-zeta und nutzte den Manchester Mark 1 zur
Berechnung von Nullstellen, wie sie in @fig-zeta gezeigt sind 
[@Tu43; @Tu53].

::: {#refs}
**Literatur**
:::

Auch Alan Turing beschäftigte sich mehrfach mit der Funktion \zeta(s) aus Gleichung 1 und nutzte den Manchester Mark 1 zur Berechnung von Nullstellen, wie sie in Abbildung 1 gezeigt sind (Turing 1943, 1953).

Literatur

Turing, A. M. 1943. „A method for the calculation of the zeta-function“. Proc. London Math. Soc. (2) 48: 180–97. https://doi.org/10.1112/plms/s2-48.1.180.
———. 1953. „Some calculations of the Riemann zeta-function“. Proc. London Math. Soc. (3) 3: 99–117. https://doi.org/10.1112/plms/s3-3.1.99.

Webseiten

Statische Webseiten

  • Bestehen nur aus unveränderlichen Dateien, die direkt von einem Webserver ausgeliefert werden (HTML, CSS, Javascript, Bilder, …)

  • Bieten hohe Performance bei minimalen Hosting-Anforderungen \to nachhaltig

  • Sind sicherer, da Verzicht auf kompliziertes Back-end aus Datenbanken und Rendering-Code (PHP, Python, Node.js)

  • Werden nur bei Änderungen mit einem Programm (Hugo, Jekyll, Quarto) aus Quelldaten neu erzeugt

Quarto

  • Verwandelt einen Ordner mit Markdown-Dateien in ansprechende Webseiten
  • Einfache Konfiguration mit einer YAML-Datei _quarto.yml
  • Menüs, Header, Footer, Side-Bars, …
  • Edit-Links zu einer Git-Plattform eigener Wahl
  • Responsive web design
  • Eingebaute Such-Funktion
  • CI/CD tauglich

IT4Science

Prototyp für eine neue IT4Science Webseite besteht aus:

.
├── about.qmd
├── datenschutz.qmd
├── events
│   ├── days2022.qmd
│   ├── days2023.qmd
│   └── days2025.qmd
├── events.qmd
├── impressum.qmd
├── index.qmd
├── _quarto.yml
├── README.md
├── styles.css
└── _variables.yml

Konfiguration _quarto.yml:

project:
  type: website

website:
  title: "{{< var it4s >}}"
  repo-url: https://gitlab.mpi-klsb.mpg.de/weisse_at_mpim-bonn.mpg.de/it4science
  repo-actions: [edit]
  navbar:
    left:
      - href: index.qmd
        text: Home
      - events.qmd
      - about.qmd
  page-footer:
    right: |
      [Impressum](/impressum.html) | [Datenschutzhinweis](/datenschutz.html)

format:
  html:
    theme:
      - cosmo
      - brand
    css: styles.css
    toc: true
    link-external-icon: true
    link-external-filter: '^(?:http:|https:)\/\/.*\.mpg\.de\/'

Screenshots

\qquad

Suche

Calabi-Yau Datenbank

  • Kombiniert ein PostgREST API Backend mit einem Quarto Frontend, siehe mein anderer Vortrag
  • Grundgerüst und die meisten Seiten basieren auf Quarto-Markdown
  • Wenige Spezialseiten nutzen eingebettes HTML und Javascript

Struktur

.
├── aesz.qmd
├── brand
│   ├── _brand.yml
│   ├── favicon.png
│   ├── icon_blank.png
│   └── icon.png
├── contributors.qmd
├── datenschutz.qmd
├── european-journal-of-mathematics.csl
├── files
│   ├── auto-render.min.js
│   ├── copy-button.css
│   ├── copy-button.svg
│   ├── ejs.min.js
│   ├── fonts
│   │   ├── KaTeX_AMS-Regular.woff2
│   │   ├── …
│   │   └── KaTeX_Typewriter-Regular.woff2
│   ├── forms.css
│   ├── get-n-render-op.js
│   ├── jquery.min.js
│   ├── katex.min.css
│   ├── katex.min.js
│   ├── print.css
│   ├── query-builder.default.min.css
│   ├── query-builder.standalone.min.js
│   └── search-ops.js
├── impressum.qmd
├── index.qmd
├── latest-jslibs.sh
├── operator.qmd
├── _quarto.yml
├── README.md
├── references.bib
├── references.qmd
└── swagger.qmd

---
title: Search Calabi-Yau operators
page-layout: full
include-in-header:
  text: |
    <link rel="stylesheet" href="files/katex.min.css">
    <link rel="stylesheet" href="files/query-builder.default.min.css">
    <script src="files/ejs.min.js"></script>
    <script src="files/katex.min.js"></script>
    <script src="files/auto-render.min.js"></script>
    <script src="files/jquery.min.js"></script>
    <script src="files/query-builder.standalone.min.js"></script>
---
```{=html}
<div id="operatorSearch"></div>
<div class="btn-group">
  <button id="btn-get" class="btn btn-primary">Search</button>
  <button id="btn-set" class="btn btn-success">Example</button>
  <button id="btn-reset" class="btn btn-warning">Clear</button>
</div>

<div id="operatorResults"></div>

<script src="files/search-ops.js"></script>
```

Screenshots

Zusammenfassung

\qquad