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:
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.
Du kannst auf eine andere Seite verlinken.
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.
Relative Bildpfade werden auch für lokal in Ihrem Projekt gespeicherte Bilder unterstützt.
Ü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:
Automatische Überschriften-Ankerlinks
Wenn du Überschriften in Markdown verwendst, erhaltst du automatisch Ankerlinks, so dass du direkt auf bestimmte Abschnitte deiner Seite verlinken kannst:
Ü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
Benutzerdefinierte Nebenbemerkungstitel
Du kannst einen benutzerdefinierten Titel für die Nebenbemerkung in eckigen Klammern nach dem Typen angeben, z.B. :::tip[Wusstest du schon?]
.
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.
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.
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.
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
{ }
: -
Markieren von Textabschnitten mit der Markierung
" "
oder regulären Ausdrücken: -
Text oder Zeilen mit
ins
oderdel
als eingefügt oder gelöscht markieren: -
Kombinieren Sie die Syntaxhervorhebung mit einer
diff
-ähnlichen Syntax:
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.
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
:
Markdoc zu einem bestehenden Projekt hinzufügen
Wenn du bereits eine Starlight-Site hast und Markdoc hinzufügen möchtest, befolge diese Schritte.
-
Füge Astros Markdoc-Integration hinzu:
-
Installiere die Starlight Markdoc-Voreinstellung:
-
Erstelle eine Markdoc-Konfigurationsdatei unter
markdoc.config.mjs
und verwende die Starlight Markdoc-Voreinstellung:
Weitere Informationen zur Syntax und den Funktionen von Markdoc findest du in der Markdoc-Dokumentation oder im Astro Markdoc-Integrationshandbuch.