Komponenten und Code

MDX: Markdown mit Komponenten

Eine Datei mit Endung .mdx darf zusätzlich zu Markdown Komponenten enthalten. Das sind wiederverwendbare Bausteine, die Starlight mitbringt oder die du selbst schreibst. Sie werden oben importiert und dann wie HTML-Tags verwendet:

import { Aside, Tabs, TabItem, Steps, FileTree } from '@astrojs/starlight/components';

<Aside type="tip" title="Ein Hinweis">
Markdown **funktioniert** auch innerhalb einer Komponente.
</Aside>

Die Starlight-Komponenten, die auf dieser Plattform am häufigsten vorkommen:

Aside

Hinweiskasten mit type note, tip, caution oder danger:

Vorsicht

So sieht caution aus.

<Aside type="caution" title="Vorsicht">So sieht `caution` aus.</Aside>

Tabs

Du siehst gerade welche. Gut für «macOS / Windows / Linux».

<Tabs>
<TabItem label="macOS">brew install node</TabItem>
<TabItem label="Windows">winget install OpenJS.NodeJS.LTS</TabItem>
</Tabs>

Steps

Nummerierte Schritte mit Verbindungslinie:

1. Erster Schritt
2. Zweiter Schritt

<Steps>
1. Erster Schritt
2. Zweiter Schritt
</Steps>

FileTree

Dateibaum aus einer Markdown-Liste, Ordner enden mit /, Text nach dem Namen wird zum Kommentar.

<FileTree>
- src/
  - content/
    - docs/ Alle Seiten
</FileTree>

Geschweifte Klammern in MDX

In MDX ist { der Beginn eines JavaScript-Ausdrucks. Im Fliesstext bricht eine einzelne geschweifte Klammer den Build. Schreib sie in Backticks oder in einen Code-Block, da sind sie harmlos. Gleiches gilt für < vor einem Wort, das wie ein Tag aussieht.

Code-Blöcke

Starlight rendert Code-Blöcke mit Expressive Code. Nach der Sprache kannst du Attribute angeben:

```bash frame="terminal" title="VM"
sudo apt update
```

```bash title="backup.sh" ins={3-4} del={5}
#!/bin/bash
set -euo pipefail
# neu:
rsync -a "$QUELLE" "$ZIEL"
cp -r "$QUELLE" "$ZIEL"
```

Attribut	Wirkung
frame="terminal"	Rahmen wie ein Terminalfenster
title="..."	Dateiname oder Beschriftung über dem Block
ins={3-4}, del={5}	Zeilen als eingefügt (grün) oder gelöscht (rot) markieren
{2}	Zeile hervorheben
wrap	Lange Zeilen umbrechen statt scrollen

Die Konvention dieser Plattform: Terminal-Sitzungen mit frame="terminal", Skripte und Konfigurationsdateien mit title, Änderungen gegenüber dem vorherigen Listing mit ins.

Diagramme mit Mermaid

Statt Bilder zu zeichnen, beschreibst du Diagramme als Text. Die Integration astro-mermaid rendert sie beim Build:

npm install astro-mermaid mermaid

astro.config.mjs

import starlight from '@astrojs/starlight';
import mermaid from 'astro-mermaid';

export default defineConfig({
  integrations: [mermaid({ theme: 'neutral', autoTheme: true }), starlight({ /* ... */ })],
});

Die Mermaid-Integration muss vor Starlight stehen. Dann:

```mermaid
flowchart LR
    A[Markdown] --> B[Build] --> C[Webserver]
```

flowchart LR
    A[Markdown] --> B[Build] --> C[Webserver]

autoTheme: true passt die Farben an Dark und Light Mode an. Mermaid kennt Flowcharts, Sequenzdiagramme, Zustandsdiagramme und mehr, die Mermaid-Dokumentation hat Beispiele.

Hands-on: Benenne 01-hallo.md in 01-hallo.mdx um, importiere Aside und Steps, und füge einen Hinweis, drei Schritte und ein Flowchart ein. Prüfe, dass der Dev-Server keine Fehler zeigt.

Aufgabe 2.3 · Eine richtige Seite

Schreibe in deinem Projekt eine Seite zu einem Thema deiner Wahl, die mindestens enthält: ein Aside, Tabs mit zwei Varianten, einen Code-Block mit frame="terminal", einen mit title und einer ins-Markierung, und ein Mermaid-Diagramm. Kopiere sie nach labs/plattform/02-inhalte/seite.mdx.

Lösung anzeigen

Ein Mermaid-Block gehört nicht in Backticks mit vier Zeichen, das war hier nur nötig, um einen Code-Block innerhalb eines Code-Blocks zu zeigen. In deiner Seite reichen drei Backticks mit mermaid als Sprache.

Selbstcheck · 3 Fragen

1. Wann braucht eine Seite die Endung .mdx statt .md?

ImmerWenn sie Komponenten importiertWenn sie Code-Blöcke enthält

2. Was bewirkt ins={3-4} an einem Code-Block?

Fügt Zeilen 3 und 4 einMarkiert Zeilen 3 und 4 als neu (grün)Versteckt Zeilen 3 und 4

3. Warum bricht «Setze {name} ein» im Fliesstext einer MDX-Datei den Build?

Weil name nicht definiert ist: geschweifte Klammern leiten in MDX einen JavaScript-Ausdruck einWeil Markdown keine Klammern kenntEs bricht nicht

Antworten prüfen