Text mit Markdown schreiben
Markdown ist eine leichtgewichtige Auszeichnungssprache, die Dokumentstruktur in Klartext ausdrückt. Überschriften, Listen, Links, Codeblöcke und Tabellen bleiben im Quelltext lesbar und lassen sich als HTML oder in anderen Formaten darstellen.
Dieser lesbare Quelltext ist der wichtigste Vorteil von Markdown. Du kannst Änderungen Zeile für Zeile prüfen, sie in Git speichern und die endgültige Typografie einem Renderer überlassen, ohne das Dokument hinter Formatierungsschaltflächen zu verstecken.
Grundlegende Syntax von Markdown
Das folgende Beispiel sammelt häufige Syntax in einer Datei. Eine Raute leitet eine Überschrift ein, während umschließende Zeichen Hervorhebungen, Links, Code und weitere Strukturen ausdrücken:
Das Beispiel nutzt Markdown-Funktionen aus Pandoc und GitHub Flavored Markdown. Tabellen und ~~durchgestrichener Text~~ sind Erweiterungen, die nicht jeder Markdown-Renderer unterstützt. Die Shell-Beispiele verwenden Bash unter macOS oder Linux. Passe Beispielpfade an deinen Übungsordner an.
# Überschrift Ebene 1
## Überschrift Ebene Zwei
### Überschrift Ebene drei
**Fetter Text**
*Kursiver Text*
~~Durchgestrichener Text~~
> Blockzitat für einen wichtigen Hinweis
1. Erster Eintrag einer geordneten Liste
2. Zweiter Eintrag einer geordneten Liste
3. Dritter Eintrag einer geordneten Liste
- Eintrag einer ungeordneten Liste
- Noch ein Eintrag
- Letzter Eintrag
[Linktext](https://example.com)
`inline code`
```python
# Codeblock
def hello_world():
print("Hallo, Welt!")
```
---
| Spalte 1 | Spalte 2 | Spalte 3 |
|----------|----------|----------|
| Wert A | Wert B | Wert C |
| Wert D | Wert E | Wert F |Arbeitsablauf mit Markdown
Behalte die Quelldatei als geprüften Inhalt und behandle gerenderte Dateien als reproduzierbare Ausgabe. Ein kurzer Ablauf genügt: erstellen, bearbeiten, validieren, umwandeln und ansehen.
Erstelle eine Datei mit der Endung .md, schreibe ihren Inhalt und wandle sie mit einem installierten Werkzeug wie Pandoc um. Mit --standalone enthält HTML den vollständigen Dokumentkopf und -rumpf. Verknüpfte Bilder und Stylesheets bleiben ohne ausdrückliches Einbetten getrennt. Für PDF-Ausgabe braucht dein Rechner zusätzlich eine kompatible PDF-Engine.
# Neue Markdown-Datei erstellen
touch document.md
# Mit Texteditor bearbeiten
nano document.md
# Mit Pandoc in HTML konvertieren
pandoc document.md --standalone -o document.html
# In PDF konvertieren, wenn eine unterstützte PDF-Engine installiert ist
pandoc document.md -o document.pdf
# Vorschau unter macOS. Linux-Desktops verwenden häufig xdg-open
open document.htmlGrundlagen der Befehlszeilenschnittstelle
Eine Befehlszeilenschnittstelle oder CLI nimmt Textbefehle über eine Shell entgegen. Jeder Befehl besteht aus einem Programmnamen, optionalen Schaltern und Argumenten wie Pfaden.
CLI-Befehle lassen sich prüfen, wiederholen, skripten und begutachten. Die Shell befolgt den angegebenen Pfad und jeden Schalter genau. Ermittle deshalb zuerst das Ziel und prüfe destruktive Schalter vor dem Ausführen.
Navigation und Erkundung von Verzeichnissen
Bevor du Dateien änderst, bestätige das aktuelle Verzeichnis, untersuche seinen Inhalt und wechsle mit einem ausdrücklichen Pfad:
# Aktuelles Arbeitsverzeichnis anzeigen
pwd
# Verzeichnisinhalte auflisten
ls
ls -l # detailliertes Format
ls -la # einschließlich versteckter Dateien
# Verzeichnis wechseln
mkdir -p "$HOME/markdown-practice"
cd "$HOME/markdown-practice"
cd .. # eine Ebene höher gehen
cd ~ # Zum Home-Verzeichnis wechseln
cd - # Zum vorherigen Verzeichnis zurückkehren
# Neues Verzeichnis erstellen
mkdir new_project
mkdir -p project/src/components # Verzeichnishierarchie erstellenOperationen mit Dateien und Verzeichnissen
Dateibefehle wirken sofort auf reale Pfade. Prüfe ein Ziel vor dem Löschen, setze Pfade mit möglichen Leerzeichen in Anführungszeichen und vermeide rekursive Force-Schalter, solange das genaue Verzeichnis nicht nachweislich entbehrlich ist.
# Dateien kopieren
cp source.txt destination.txt
cp -r source_folder/ destination_folder/
# Dateien verschieben oder umbenennen
mv old_name.txt new_name.txt
mv file.txt /path/to/new/location/
# Vor dem Löschen prüfen
pwd
ls -la unwanted_folder
rm unwanted_file.txt
rm -r unwanted_folder # Löscht rekursiv. Diesen Pfad zuerst prüfen
# Dateiinhalte anzeigen
cat file.txt # gesamte Inhalte anzeigen
head -10 file.txt # erste 10-Zeilen
tail -10 file.txt # letzten 10-Zeilen
less file.txt # Ansicht mit NavigationIntegration von Markdown mit CLI
Ein kleines Build-Skript macht die Umwandlung wiederholbar. Es sollte bei einem fehlgeschlagenen Befehl abbrechen, sein Ausgabeverzeichnis selbst anlegen, jeden Pfad zitieren und den Fall ohne Quelldatei behandeln:
# Markdown-Projekt einrichten
mkdir my-documentation
cd my-documentation
# Verzeichnisstruktur
mkdir -p {src,build,images,assets}
# Markdown-Dateien erstellen
touch src/index.md src/getting-started.md src/api-reference.md
# Build mit einem Skript automatisieren
cat << 'EOF' > build.sh
#!/bin/bash
set -eu
echo "Dokumentation wird erstellt..."
mkdir -p build
# Alle Markdown-Dateien in HTML umwandeln
for file in src/*.md; do
[ -e "$file" ] || continue
basename=$(basename "$file" .md)
pandoc "$file" -o "build/$basename.html" --standalone
echo "Konvertiert: $file -> build/$basename.html"
done
echo "Build abgeschlossen!"
EOF
# Skript ausführbar machen
chmod +x build.sh
# Build ausführen
./build.shWerkzeuge für die CLI für Markdown
Nutze die offiziellen Installationswege der Werkzeuge und prüfe anschließend die installierten Befehle, bevor ein Skript von ihnen abhängt. Pandoc wandelt Dokumente um, ein Markdown-Linter prüft die Konventionen des Quelltexts:
# Benötigte Werkzeuge prüfen
command -v pandoc
command -v markdownlint
# Markdown-Quellen prüfen
markdownlint "docs/**/*.md"
# Markdown in verschiedene Formate konvertieren
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o output.epub
# Mit benutzerdefinierter Vorlage
pandoc input.md -o output.html --template=custom.htmlBewährte Vorgehensweisen für CLI und Markdown
Speichere verfasstes Markdown in der Versionsverwaltung, validiere es vor der Umwandlung, baue in ein ersetzbares Ausgabeverzeichnis und prüfe den Diff vor dem Commit:
Das Verzeichnis site enthält in diesem Beispiel ausschließlich erzeugte Ausgaben und wird beim Build ersetzt. Speichere selbst geschriebene Dateien in docs, nicht in site.
# Wiederholbarer lokaler Dokumentations-Build
cat << 'EOF' > update-docs.sh
#!/bin/bash
set -eu
SOURCE_DIR="docs"
OUTPUT_DIR="site"
STAGING_DIR=$(mktemp -d "./.site-build.XXXXXX")
trap 'rm -rf "$STAGING_DIR"' EXIT
source_files=()
while IFS= read -r -d '' file; do
source_files+=("$file")
done < <(find "$SOURCE_DIR" -type f -name "*.md" -print0)
if [ "${#source_files[@]}" -eq 0 ]; then
echo "Keine Markdown-Quellen gefunden" >&2
exit 1
fi
markdownlint "${source_files[@]}"
for file in "${source_files[@]}"; do
relative_path=${file#"$SOURCE_DIR"/}
output_file="$STAGING_DIR/${relative_path%.md}.html"
mkdir -p "$(dirname "$output_file")"
pandoc "$file" -o "$output_file" --standalone
done
[ ! -e "$OUTPUT_DIR" ] || rm -r -- "$OUTPUT_DIR"
mv "$STAGING_DIR" "$OUTPUT_DIR"
trap - EXIT
EOF
chmod +x update-docs.sh
./update-docs.sh
# Änderungen am Quelltext vor dem Commit prüfen
git diff --check
git diff -- docsEchtes Projektbeispiel
Das letzte Beispiel erstellt vier Quelldateien und verbindet sie zu einem eigenständigen HTML-Dokument. Jeder Eingabepfad ist ausdrücklich genannt. Fehlt eine Datei, schlägt der Build mit einer Fehlermeldung fehl:
# Projektstruktur einrichten
mkdir ai-project-docs
cd ai-project-docs
# Verzeichnisstruktur erstellen
mkdir -p docs/api docs/tutorials docs/guides scripts build
# Zentrale Dokumentationsdatei erstellen
cat << 'EOF' > docs/README.md
# Dokumentation des KI-Projekts
## Was das Werkzeug tut
Vollständige Dokumentation für ein KI-Programmierprojekt.
## Wie ein Dokument aufgebaut ist
- [API-Referenz](#api)
- [Tutorials](#tutorials)
- [Benutzerhandbücher](#guides)
EOF
# Verknüpfte Seiten erstellen
cat << 'EOF' > docs/api/README.md
# API-Referenz {#api}
Beschreibe jede öffentliche Schnittstelle und ergänze ein geprüftes Beispiel.
EOF
cat << 'EOF' > docs/tutorials/README.md
# Tutorials {#tutorials}
Führe den Leser durch eine vollständige Aufgabe.
EOF
cat << 'EOF' > docs/guides/README.md
# Benutzerleitfäden {#guides}
Erkläre wiederkehrende Abläufe und ihre Sicherheitsgrenzen.
EOF
# Automatisiertes Build-Skript erstellen
cat << 'EOF' > scripts/build-docs.sh
#!/bin/bash
set -eu
mkdir -p build
pandoc docs/README.md docs/api/README.md docs/tutorials/README.md docs/guides/README.md --standalone --output build/index.html
echo "Dokumentations-Build abgeschlossen!"
EOF
chmod +x scripts/build-docs.sh
# Build ausführen
./scripts/build-docs.shMarkdown hält die Dokumentstruktur in der Versionsverwaltung lesbar. Mit einer CLI lassen sich dieselben Prüf- und Umwandlungsschritte erneut ausführen. Ein verlässlicher Ablauf bewahrt diese Grenze: Bearbeite die Quelle, prüfe Befehle und Pfade, erzeuge die Ausgabe neu und begutachte die entstandenen Änderungen.