Diataxis Setup mit Quarto

Diataxis Setup mit Quarto – ohne und mit Python.

Versionen:

ohne Python

Voraussetzung: Quarto ist installiert, siehe grundinstallation-linuxmint-22.3-xfce

1. Quarto Projektverzeichnis erstellen

Doku: https://quarto.org/docs/websites/

Projekt-Root definieren:

QUARTOPROJECT="${HOME}/b/l/LA_2026_ws/dsci-lab-ws2026"
QMD="${QUARTOPROJECT}/qmd"
mkdir -p "$QUARTOPROJECT"
cd "$QUARTOPROJECT"

Die Quarto-Dateien legen wir in das (im Prinzip beliebig benennbare) Verzeichnis qmd.

quarto create project website qmd

Quarto legt eine initiale Website im Verzeichnis qmd an, die wir dann auch schon anschauen können. Aus Bequemlichkeit wechseln wir in das Verzeichnis qmd.

cd "${QUARTOPROJECT}/qmd"
ls -als
quarto preview
# (Beenden mit CTRL-C)

Website statisch erstellen:

quarto render

Achtung: Hier ist noch kein Python executable code enthalten. Wenn auch Python ausgeführt werden soll, muss man Quarto mit uv starten, s.u..

2. Diataxis-Skelett

einfacher: Diataxis-Skelett als zip-Datei downloaden. Beschreibung hier: alles selbst anlegen

Wir wollen typische Diataxis-Ordner und -Dateien anlegen, und auch die Navigation links weitgehend automatisch erstellen.

Schritt 1: Verzeichnisse und exemplarische Dateien anlegen

cd "${QUARTOPROJECT}/qmd"
mkdir -p {tutorial,howto,explanation,reference,data,private,ai,journal}

Die wichtigsten Index-Dateien per Skript anlegen:

cd "${QUARTOPROJECT}/qmd"
mkdir -p {tutorial,howto,explanation,reference,data,private,ai,journal}
for dir in tutorial howto explanation reference data private ai journal; do
  cat <<EOF > "$dir/00_index-$dir.qmd"
---
title: "Index $dir"
listing: table
---
EOF
done

Damit die Verzeichnisse nicht leer sind minimale Beispiel-Dateien anlegen:

cd "${QUARTOPROJECT}/qmd"
mkdir -p {tutorial,howto,explanation,reference,data,private,ai,journal}
for dir in tutorial howto explanation reference data private ai journal; do
  cat <<EOF > "$dir/example-$dir.qmd"
---
title: "Beispiel $dir"
---
EOF
done

Kontrolle, das haben wir nun erzeugt:

ls -a *

Schritt 2: Quarto-Projekt differenzierter konfigurieren

Dazu die Datei _quarto.yml im Verzeichis $QUARTOPROJECT editieren:

cat << 'EOF' > _quarto.yml
# _quarto.yml
project:
  type: website

format:
  html:
    theme: cosmo
    toc: true

execute:
  freeze: auto
  warning: false
  error: false

website:
  title: "mein projekt"

  sidebar:
    contents:
      - auto: tutorial
      - auto: howto
      - auto: explanation
      - auto: reference
      - auto: data
      - auto: ai
      - auto: journal      
EOF

Die neu strukturierte, leere Website anschauen:

cd "${QUARTOPROJECT}/qmd"
quarto preview
# (Beenden mit CTRL-C)

Ergebnis: Wir können jetzt Markdown-Dateien mit Quarto rendern; es entsteht eine leere Website in Diataxis-Struktur.

Quarto mit Python

Voraussetzung: uv ist installiert, siehe XXX

uv

Initialisierung im Verzeichnis qmd als minimales Python-Projekt

cd "${QUARTOPROJECT}/qmd"
uv init --bare  --python 3.12
uv add --dev jupyterlab notebook jupytext ipykernel jupyterlab-quarto quarto-cli
uv add pandas # und weitere andere projektspezifische Module

Damit wurde in diesem Verzeichnis (und damit genau für dieses Verzeichnis) die zentrale Konfigurations-Datei pyproject.toml angelegt.

cat pyproject.toml

EXKURS: Python in diesem Verzeichnis wieder “löschen” mit rm pyproject.toml, dann neu “initialisieren” mit uv init usw.

Fancy: Wir wollen konsequent mit qmd-Dateien arbeiten, auch mit eingebettetem Python-Code. Dazu konfigurieren wir mit jupytext ein automatischen Pairing von *.ipynb und *.qmd:

cat << 'EOF' > jupytext.toml
# Aktiviert die automatische Paarung mit .qmd-Dateien für neue Notebooks
default_notebook_metadata_filter = "jupytext"
formats = "qmd,ipynb"
EOF

Dank der automatischen Paarung (s.o) wird jetzt für jede Datei automatisch eine Version *.qmd und eine *.ipynb synchron bereitgehalten und bei jedem Schreibvorgang synchronisiert.

Das sollte jetzt gehen:

uv run python --version
uv run jupyter --version
uv run quarto check

Ausprobieren: Eine erste qmd-Datei anlegen, die Python Code enthält, z.B. qmd/howto/welche-python-version.qmd

DATEI_PFAD="howto/python_version_test.qmd"
cat << 'EOF' > "$DATEI_PFAD"
---
title: "Welche Python-Version?"
format: html
---
Welche Python-Version ist aktuell aktiv?

::: {#85caa3af .cell execution_count=1}
``` {.python .cell-code}
import sys
print(f"Die Antwort auf alle Fragen: {6*7}, genutztes Python:\n{sys.executable}")
Die Antwort auf alle Fragen: 42, genutztes Python:
/home/dsci/b/l/LA_2026_ws/dsci-lab-ws2026/qmd/.venv/bin/python3

:::

EOF


Jupyter Notebook oder Lab starten:

```bash
uv run jupyter notebook
uv run jupyter lab

Website anschauen:

cd "${QUARTOPROJECT}/qmd"
uv run quarto preview

JupyterLab oder Jupyter Notebook starten, dann spielerisch howto/welche-python-version.ipynb oder howto/welche-python-version.qmd editieren: Was passiert?

cd "${QUARTOPROJECT}/qmd"
uv run jupyter lab

Für die tägliche Arbeit sind typischerweise mehrere Terminals sinnvoll:

Terminal 1: Quarto-Live-Vorschau starten, oder andere Quarto-Kommandos absetzen:

cd "${QUARTOPROJECT}/qmd"
quarto preview

Terminal 2: Programmier-IDE wie z.B. JupyterLab oder Jupyter Notebook managen:

cd "${QUARTOPROJECT}/qmd"
uv run jupyter lab

Terminal 3 (optional): In einem einfachen Texteditor (z.B. mousepad, xed) oder einem Profi-Editor (empfohlen: nvmim) die Markdown-Dateien bearbeiten, z.B. die Datei qmd/tutorial/example-tutorial.qmd:

cd "${QUARTOPROJECT}/qmd"
xed tutorial/example-tutorial.qmd

git

.gitignore im Hauptverzeichis (Eltern-Verzeichnis von qmd/)

cd "${QUARTOPROJECT}"
cat << 'EOF' > .gitignore
# .gitignore
# Quarto-Ausgaben
_site/
.quarto/
*_files/

# ggf. mit Jupyter book Version 1 gebaute Verzeichnisse
_build

# Jupyter- und Python-Artefakte
.ipynb_checkpoints/
__pycache__/
*.py[cod]

# Lokale Umgebungen und lokale Konfiguration
.venv/
.env

# Keine Jupyter-JSON-Notebooks versionieren
*.ipynb

# Private Inhalte
qmd/private/

# Auch gleich die üblichen Python-Dateien in -gitignore ausschließen?
# Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info

EOF