Zum Inhalt springen

Inhalte in Markdown verfassen

Starlight unterstützt die gesamte Bandbreite der Markdown Syntax in .md Dateien sowie Frontmatter YAML um Metadaten wie Titel und Beschreibung zu definieren.

Bitte prüfe die MDX docs oder Markdoc docs, wenn du diese Dateiformate verwendest, da die Unterstützung und Verwendung von Markdown unterschiedlich sein kann.

Frontmatter

Du kannst einzelne Seiten in Starlight anpassen, indem du Werte in deinen Frontmatter festlegst. Frontmatter wird oben in deinen Dateien zwischen ----Trennzeichen festgelegt:

src/content/docs/example.md
---
title: Mein Seitentitel
---
Nach dem zweiten `---` folgt der Seiteninhalt.

Jede Seite muss mindestens einen title enthalten. Alle verfügbaren Felder und Informationen zum Hinzufügen benutzerdefinierter Felder findst du in der Frontmatter-Referenz.

Inline-Stile

Text kann fett, italic, oder durchgestrichen sein.

Text kann **fett**, _italic_, oder ~~durchgestrichen~~ sein.

Du kannst auf eine andere Seite verlinken.

Du kannst [auf eine andere Seite](/de/getting-started/) verlinken.

Du kannst inline code mit Backticks hervorheben.

Du kannst `inline code` mit Backticks hervorheben.

Bilder

Bilder in Starlight verwenden Astros eingebaute optimierte Asset-Unterstützung.

Markdown und MDX unterstützen die Markdown-Syntax für die Anzeige von Bildern, einschließlich Alt-Text für Bildschirmleser und unterstützende Technologien.

Eine Illustration von Planeten und Sternen mit dem Wort "Astro"

![Eine Illustration von Planeten und Sternen mit dem Wort "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-imag)

Relative Bildpfade werden auch für lokal in Ihrem Projekt gespeicherte Bilder unterstützt.

src/content/docs/page-1.md
![Ein Raketenschiff im Weltraum](../../assets/images/rocket.svg)

Überschriften

Mit einer Überschrift kannst du den Inhalt strukturieren. Überschriften in Markdown werden durch eine Reihe von # am Anfang der Zeile gekennzeichnet.

Wie du Seiteninhalte in Starlight strukturierst

Starlight ist so konfiguriert, dass es automatisch den Seitentitel als Überschrift verwendet und eine “Übersicht”-Überschrift an den Anfang des Inhaltsverzeichnisses jeder Seite setzt. Wir empfehlen, jede Seite mit normalem Text zu beginnen und die Seitenüberschriften ab <h2> zu verwenden:

---
title: Markdown Anleitung
description: Wie man Markdown in Starlight benutzt
---
Diese Seite beschreibt, wie man Markdown in Starlight benutzt.
## Inline-Stile
## Überschriften

Wenn du Überschriften in Markdown verwendst, erhaltst du automatisch Ankerlinks, so dass du direkt auf bestimmte Abschnitte deiner Seite verlinken kannst:

---
title: Meine Seite mit Inhalt
description: Wie man Starlights eingebaute Ankerlinks benutzt
---
## Einleitung
Ich kann auf [meine Schlussfolgerung](#schlussfolgerung) weiter unten auf derselben Seite verlinken.
## Schlussfolgerung
`https://meine-site.com/seite1/#einleitung` navigiert direkt zu meiner Einleitung.

Überschriften der Ebene 2 (<h2>) und der Ebene 3 (<h3>) werden automatisch im Inhaltsverzeichnis der Seite angezeigt.

Erfahre mehr darüber, wie Astro Kopfzeilen-IDs verarbeitet, in der Astro-Dokumentation.

Nebenbemerkungen

Nebenbemerkungen (auch bekannt als “Ermahnungen” oder “Callouts”) sind nützlich, um sekundäre Informationen neben dem Hauptinhalt einer Seite anzuzeigen.

Starlight bietet eine eigene Markdown-Syntax für die Darstellung von Nebeninformationen. Seitenblöcke werden mit einem Paar dreifacher Doppelpunkte ::: angezeigt, um den Inhalt zu umschließen, und können vom Typ note, tip, caution oder danger sein.

Sie können alle anderen Markdown-Inhaltstypen innerhalb einer Nebenbemerkung verschachteln, allerdings eignen sich diese am besten für kurze und prägnante Inhaltsstücke.

Nebenbemerkung note

:::note
Starlight ist ein Toolkit für Dokumentations-Websites, das mit [Astro](https://astro.build/de) erstellt wurde. Du kannst mit diesem Befehl beginnen:
```sh
npm create astro@latest -- --template starlight
```
:::

Benutzerdefinierte Nebenbemerkungstitel

Du kannst einen benutzerdefinierten Titel für die Nebenbemerkung in eckigen Klammern nach dem Typen angeben, z.B. :::tip[Wusstest du schon?].

:::tip[Wusstest du schon?]
Astro hilft dir, schnellere Websites mit ["Islands Architecture"](https://docs.astro.build/de/concepts/islands/) zu erstellen.
:::

Weitere Typen

Vorsichts- und Gefahrenhinweise sind hilfreich, um die Aufmerksamkeit des Benutzers auf Details zu lenken, über die er stolpern könnte. Wenn du diese häufig verwenden, kann das auch ein Zeichen dafür sein, dass die Sache, die Sie dokumentieren, von einem neuen Design profitieren könnte.

:::caution
Wenn du nicht sicher bist, ob du eine großartige Dokumentseite willst, überlege es dir zweimal, bevor du [Starlight](/de/) verwendest.
:::
:::danger
Deine Benutzer können dank hilfreicher Starlight-Funktionen produktiver sein und dein Produkt einfacher nutzen.
- Übersichtliche Navigation
- Benutzer-konfigurierbares Farbthema
- [i18n-Unterstützung](/de/guides/i18n/)
:::

Blockzitate

Dies ist ein Blockzitat, das üblicherweise verwendet wird, wenn eine andere Person oder ein Dokument zitiert wird.

Blockzitate werden durch ein ”>” am Anfang jeder Zeile gekennzeichnet.

> Dies ist ein Blockzitat, das üblicherweise verwendet wird, wenn eine andere Person oder ein Dokument zitiert wird.
>
> Blockzitate werden durch ein ">" am Anfang jeder Zeile gekennzeichnet.

Codeblöcke

Ein Codeblock wird durch einen Block mit drei Backticks ``` am Anfang und Ende gekennzeichnet. Du kannst die verwendete Programmiersprache nach den ersten drei Backticks angeben.

// Javascript-Code mit Syntaxhervorhebung.
var fun = function lang(l) {
dateformat.i18n = require('./lang/' + l);
return true;
};
```js
// Javascript-Code mit Syntaxhervorhebung.
var fun = function lang(l) {
dateformat.i18n = require('./lang/' + l);
return true;
};
```

Expressive Code-Merkmale

Starlight verwendet Expressive Code, um die Formatierungsmöglichkeiten für Codeblöcke zu erweitern. Die Textmarker und Fensterrahmen-Plugins von Expressive Code sind standardmäßig aktiviert. Die Darstellung von Codeblöcken kann mit Starlights expressiveCode Konfigurationsoption konfiguriert werden.

Textmarkierungen

Du kannst bestimmte Zeilen oder Teile deiner Codeblöcke hervorheben, indem du Expressive Code Textmarkierungen in der ersten Zeile deines Codeblocks verwendest. Verwende geschweifte Klammern ({ }), um ganze Zeilen hervorzuheben, und Anführungszeichen, um Textabschnitte zu markieren.

Es gibt drei Hervorhebungsstile: neutral, um auf den Code aufmerksam zu machen, grün, um eingefügten Code zu kennzeichnen, und rot, um gelöschten Code zu kennzeichnen. Sowohl Text als auch ganze Zeilen können mit der Standardmarkierung oder in Kombination mit ins= und del= markiert werden, um die gewünschte Hervorhebung zu erzielen.

Expressive Code bietet mehrere Optionen zur Anpassung des visuellen Erscheinungsbildes deiner Codebeispiele. Viele dieser Optionen können kombiniert werden, um sehr anschauliche Codebeispiele zu erstellen. Bitte schaue dir die Expressive Code Dokumentation an, um dich über die umfangreichen Optionen zu informieren. Einige der gebräuchlichsten Beispiele sind unten aufgeführt:

  • Markiere ganze Zeilen und Zeilenbereiche mit dem Marker { }:

    function demo() {
    // Diese Zeile (#2) und die nächste Zeile sind hervorgehoben
    return 'This is line #3 of this snippet';
    }
    ```js {2-3}
    function demo() {
    // Diese Zeile (#2) und die nächste Zeile sind hervorgehoben
    return 'This is line #3 of this snippet';
    }
    ```
  • Markieren von Textabschnitten mit der Markierung " " oder regulären Ausdrücken:

    // Auch einzelne Begriffe können hervorgehoben werden
    function demo() {
    return 'Auch reguläre Ausdrücke werden unterstützt';
    }
    ```js "einzelne Begriffe" /Auch.*unterstützt/
    // Auch einzelne Begriffe können hervorgehoben werden
    function demo() {
    return 'Auch reguläre Ausdrücke werden unterstützt';
    }
    ```
  • Text oder Zeilen mit ins oder del als eingefügt oder gelöscht markieren:

    function demo() {
    console.log('Dies sind eingefügte und gelöschte Markertypen');
    // Die return-Anweisung verwendet den Standard-Markierungstyp
    return true;
    }
    ```js "return true;" ins="eingefügte" del="gelöschte"
    function demo() {
    console.log('Dies sind eingefügte und gelöschte Markertypen');
    // Die return-Anweisung verwendet den Standard-Markierungstyp
    return true;
    }
    ```
  • Kombinieren Sie die Syntaxhervorhebung mit einer diff-ähnlichen Syntax:

    function thisIsJavaScript() {
    // Dieser gesamte Block wird als JavaScript hervorgehoben,
    // und wir können ihm immer noch Diff-Markierungen hinzufügen!
    console.log('Zu entfernender alter Code')
    console.log('Neuer, glänzender Code!')
    }
    ```diff lang="js"
    function thisIsJavaScript() {
    // Dieser gesamte Block wird als JavaScript hervorgehoben,
    // und wir können ihm immer noch Diff-Markierungen hinzufügen!
    - console.log('Zu entfernender alter Code')
    + console.log('Neuer, glänzender Code!')
    }
    ```

Rahmen und Überschriften

Codeblöcke können innerhalb eines fensterähnlichen Rahmens dargestellt werden. Ein Rahmen, der wie ein Terminalfenster aussieht, wird für Shell-Skriptsprachen (z.B. bash oder sh) verwendet. Andere Sprachen werden in einem Rahmen im Stil eines Code-Editors angezeigt, wenn sie einen Titel enthalten.

Der optionale Titel eines Code-Blocks kann entweder mit einem title="..."-Attribut gesetzt werden, das den öffnenden Backticks und dem Sprachbezeichner des Code-Blocks folgt, oder mit einem Dateinamenkommentar in den ersten Zeilen des Codes.

Details

Details (auch bekannt als „Offenlegungen“ oder „Akkordeons“) sind nützlich, um Inhalte zu verbergen, die nicht unmittelbar relevant sind. Die Nutzer können auf eine kurze Zusammenfassung klicken, um den gesamten Inhalt zu sehen.

Verwende die Standard-HTML-Elemente <details> und <summary> in deinem Markdown-Inhalt, um ein Offenlegungs-Widget zu erstellen.

Du kannst jede andere Markdown-Syntax innerhalb eines <Details>-Elements verschachteln.

Wo und wann ist das Sternbild Andromeda am besten zu sehen?

Das Sternbild Andromeda ist am Nachthimmel im Monat November in Breitengraden zwischen +90° und −40° am besten sichtbar.

<details>
<summary>Wo und wann ist das Sternbild Andromeda am besten zu sehen?</summary>
Das Sternbild [Andromeda](<https://de.wikipedia.org/wiki/Andromeda_(Sternbild)>) ist am Nachthimmel im Monat November in Breitengraden zwischen `+90°` und `−40°` am besten sichtbar.
</details>

Andere allgemeine Markdown-Funktionen

Starlight unterstützt alle anderen Markdown-Autorensyntaxen, wie Listen und Tabellen. Einen schnellen Überblick über alle Markdown-Syntaxelemente findest du im Markdown Cheat Sheet von The Markdown Guide.

Erweiterte Markdown- und MDX-Konfiguration

Starlight verwendet Astros Markdown- und MDX-Renderer, der auf remark und rehype aufbaut. Du kannst eine Unterstützung für eigene Syntax und Verhalten hinzufügen, indem du remarkPlugins oder rehypePlugins in deiner Astro-Konfigurationsdatei hinzufügst. Weitere Informationen findest du unter “Markdown konfigurieren” in der Astro-Dokumentation.

Markdoc

Starlight unterstützt die Erstellung von Inhalten in Markdoc mithilfe der experimentellen Astro Markdoc-Integration und der Starlight Markdoc-Voreinstellung.

Erstelle ein neues Projekt mit Markdoc

Starte ein neues Starlight-Projekt mit vorkonfiguriertem Markdoc mit create astro:

Terminal-Fenster
npm create astro@latest -- --template starlight/markdoc

Markdoc zu einem bestehenden Projekt hinzufügen

Wenn du bereits eine Starlight-Site hast und Markdoc hinzufügen möchtest, befolge diese Schritte.

  1. Füge Astros Markdoc-Integration hinzu:

    Terminal-Fenster
    npx astro add markdoc
  2. Installiere die Starlight Markdoc-Voreinstellung:

    Terminal-Fenster
    npm install @astrojs/starlight-markdoc
  3. Erstelle eine Markdoc-Konfigurationsdatei unter markdoc.config.mjs und verwende die Starlight Markdoc-Voreinstellung:

    import { defineMarkdocConfig } from '@astrojs/markdoc/config';
    import starlightMarkdoc from '@astrojs/starlight-markdoc';
    export default defineMarkdocConfig({
    extends: [starlightMarkdoc()],
    });

Weitere Informationen zur Syntax und den Funktionen von Markdoc findest du in der Markdoc-Dokumentation oder im Astro Markdoc-Integrationshandbuch.