# Markdown und Befehlszeilenschnittstellen > For AI agents: use [llms.txt](https://nakafa.com/llms.txt) for the site index. Markdown versions are available by appending `.md` to content URLs or sending `Accept: text/markdown`. URL: https://nakafa.com/de/faecher/ki-und-data-science/ki-programmierung/markdown-und-kommandozeile Source: https://raw.githubusercontent.com/nakafaai/aksara/992eb09ded1422859aca3966c80b52a16b2832f4/packages/corpus/material/lesson/ai-ds/ai-programming/markdown-cli/de.mdx Schreibe Markdown und nutze sichere Kommandozeilenabläufe, um Dokumentation zu prüfen, umzuwandeln und zu versionieren. --- ## 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. File: basic-syntax.md ```markdown # Ü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) ![Alternativtext](image.jpg) `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. File: markdown-workflow.sh ```bash # 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.html ``` ## Grundlagen 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: File: navigation-commands.sh ```bash # 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 erstellen ``` ### Operationen 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. File: file-operations.sh ```bash # 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 Navigation ``` ### Integration 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: File: markdown-cli-workflow.sh ```bash # 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.sh ``` ### Werkzeuge 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: File: markdown-tools.sh ```bash # 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.html ``` ### Bewä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`. File: best-practices.sh ```bash # 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 -- docs ``` ### Echtes 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: File: project-example.sh ```bash # 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.sh ``` Markdown 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.