Markdown

Markdown wird h├Ąufig verwendet, um textlastige Inhalte wie Blog-Beitr├Ąge und Dokumentationen zu erstellen. Astro bietet eine integrierte Unterst├╝tzung von Markdown mit einigen zus├Ątzlichen Funktionen wie der Verwendung von JavaScript-Ausdr├╝cken und Astro-Komponenten direkt in deinem Markdown.

Astro behandelt jede .md-Datei innerhalb des Verzeichnisses /src/pages als eine Seite. Wenn du eine Datei in diesem Verzeichnis oder einem beliebigen Unterverzeichnis ablegst, wird automatisch eine Seitenroute erstellt, die den Pfadnamen der Datei verwendet.

­čôÜ Lies mehr ├╝ber Astros dateibasiertes Routing.

Der einfachste Einstieg in die Verwendung von Markdown mit Astro besteht darin, die Datei src/pages/index.md als Startseiten-Route f├╝r dein Projekt zu erstellen. Kopiere dann den untenstehenden Beispielinhalt in die Datei und sieh dir den gerenderten HTML-Code auf der Startseite deines Projekts an. Du findest sie normalerweise unter http://localhost:4321/.

src/pages/index.md
---
title: Hallo Welt
---
# Hi!
Das ist deine erste Markdown-Seite. Sie ist wahrscheinlich
nicht besonders gestaltet, obwohl Markdown durchaus
**fett** und _kursiv_ unterst├╝tzt.
Um mehr ├╝ber das Hinzuf├╝gen eines Layouts zu deiner Seite
zu erfahren, lies den n├Ąchsten Abschnitt **Markdown-Layouts**.

Markdown-Seiten unterst├╝tzen eine spezielle Frontmatter-Eigenschaft namens layout, die den relativen Pfad zu einer Astro-Layout-Komponente definiert. Diese Komponente umgibt deinen Markdown-Inhalt und stellt ein Seitenger├╝st und alle anderen enthaltenen Elemente der Seitenvorlage bereit.

---
layout: ../layouts/BasisLayout.astro
---

Ein typisches Layout f├╝r Markdown-Seiten beinhaltet Folgendes:

  1. Eine content-Eigenschaft, um auf die Frontmatter-Daten der Markdown-Seite zuzugreifen.
  2. Einen Standard-<slot />, der bestimmt, wo im Layout der Markdown-Inhalt der Seite gerendert werden soll.
src/layouts/BasisLayout.astro
---
// 1. Die content-Eigenschaft bietet Zugriff auf Frontmatter-Daten
const { content } = Astro.props;
---
<html>
<head>
<!-- F├╝ge hier andere Kopfzeilen-Elemente wie Stile und Meta-Tags hinzu. -->
<title>{content.title}</title>
</head>
<body>
<!-- F├╝ge hier andere UI-Komponenten wie gemeinsame Kopf- und Fu├čzeilen hinzu. -->
<h1>{content.title} von {content.author}</h1>
<!-- 2. Der gerenderte HTML-Code wird an den Standard-Slot ├╝bergeben. -->
<slot />
<p>Geschrieben am: {content.date}</p>
</body>
</html>

Die Eigenschaft content enth├Ąlt auch die Untereigenschaft astro, die Zugriff auf zus├Ątzliche Metadaten der Seite bietet, z. B. mit source auf den vollst├Ąndigen Quellcode und mit headers auf alle ├ťberschriften der Markdown-Seite.

Ein Beispiel f├╝r das content-Objekt eines Blogbeitrags k├Ânnte wie folgt aussehen:

{
/** Frontmatter eines Blogbeitrags
"title": "Astro-Release 0.18",
"date": "Dienstag, 27. Juli 2021",
"author": "Matthew Phillips",
"description": "Astro 0.18 ist unser gr├Â├čtes Release seit Astros Einf├╝hrung.",
"draft": false,
"keywords": ["Astro", "Release", "Ank├╝ndigung"]
**/
"astro": {
"headers": [
{
"depth": 1,
"text": "Astro-Release 0.18",
"slug": "astro-release-018"
},
{
"depth": 2,
"text": "Responsive partielle Hydratation",
"slug": "responsive-partielle hydratation"
}
/* ... */
],
"source": "# Astro-Release 0.18\nVor etwas mehr als einem Monat haben wir die erste ├Âffentliche Beta [...]"
},
"url": ""
}

Frontmatter als Komponenteneigenschaften (Props)

Abschnitt betitelt Frontmatter als Komponenteneigenschaften (Props)

Jede Astro-Komponente (nicht nur dein Layout!) kann auf die in deinem Markdown definierten Frontmatter-Daten ├╝ber die Eigenschaften des Astro.props-Objekts zugreifen. Das YAML-Frontmatter-Format erlaubt die Verwendung mehrerer Datentypen und erm├Âglicht dir so, noch umfangreichere Metainformationen aus jedem Blog-Beitrag zu erfassen und sie auf deiner gesamten Astro-Website zu verwenden.

Der Zugriff auf diese Werte ist aus jeder .astro-Datei heraus m├Âglich und funktioniert genau so, wie wir es oben f├╝r Markdown-Layouts beschrieben haben.

Astro verwendet github-slugger, um allen ├ťberschriften in Markdown-Dateien automatisch generierte IDs zuzuweisen. Falls einer ├ťberschrift bereits eine benutzerdefinierte ID zugewiesen wurde, bleibt diese erhalten und wird nicht ├╝berschrieben.

Die automatischen IDs werden erst hinzugef├╝gt, nachdem alle anderen Markdown-Plugins ausgef├╝hrt wurden. Wenn du also ein Plugin wie rehype-toc einsetzen m├Âchtest, das schon vorher ├ťberschriften-IDs ben├Âtigt, solltest du zudem auch ein eigenes Slugging-Plugin wie rehype-slug hinzuf├╝gen.

draft: true ist ein optionaler Frontmatter-Wert, der eine einzelne .md-Seite oder einen Beitrag als ÔÇťunver├ÂffentlichtÔÇŁ markiert. Standardm├Ą├čig werden solche Seiten beim Buildvorgang der Website ausgeschlossen.

Markdown-Seiten ohne die Eigenschaft draft oder solche mit draft: false sind nicht betroffen und werden beim Buildvorgang mit ausgegeben.

src/pages/post/blogbeitrag.md
---
layout: ../../layouts/BasisLayout.astro
title: Mein Blogbeitrag
draft: true
---
Dieser Blogbeitrag ist noch in Bearbeitung.
Es wird keine Seite f├╝r ihn erstellt.
So kannst du ihn erstellen und ver├Âffentlichen:
- Ändere den Frontmatter-Wert auf `draft: false`, oder
- entferne die `draft`-Eigenschaft vollst├Ąndig.

Um zu verhindern, dass Entw├╝rfe in ein Beitragsarchiv oder eine Liste der neuesten Beitr├Ąge aufgenommen werden, kannst du die von Astro.glob() zur├╝ckgegebenen Ergebnisse filtern:

const posts = await Astro.glob('../pages/post/*.md')
.filter((post) => !post.frontmatter.draft);

ÔÜÖ´ŞĆ So ├Ąnderst du das Standardverhalten und aktivierst die Erstellung von Entwurfsseiten:

F├╝ge drafts: true zu den markdown-Einstellungen deiner astro.config.mjs hinzu.

astro.config.mjs
export default defineConfig({
markdown: {
drafts: true,
},
});

Astro unterst├╝tzt nicht nur die standardm├Ą├čige Markdown-Syntax, sondern erweitert diese um n├╝tzliche Funktionen, mit denen du deine Inhalte noch ausdrucksst├Ąrker machen kannst. Im Folgenden zeigen wir dir einige Markdown-Funktionen, die es nur in Astro gibt.

Frontmatter-Variablen k├Ânnen direkt in deinem Markdown als Eigenschaften des frontmatter-Objekts verwendet werden.

---
author: Leon
age: 42
---
# ├ťber den Autor
{frontmatter.author} ist {frontmatter.age} Jahre alt
und lebt in Toronto, Kanada.

Verwendung von Komponenten in Markdown

Abschnitt betitelt Verwendung von Komponenten in Markdown

├ťber die Frontmatter-Eigenschaft setup kannst du Komponenten in Markdown-Dateien importieren und gemeinsam mit Markdown-Inhalten verwenden. Das frontmatter-Objekt steht auch allen importierten Komponenten zur Verf├╝gung.

---
layout: ../layouts/BasisLayout.astro
setup: |
import Author from '../../components/Author.astro'
import Biography from '../components/Biography.jsx'
author: Leon
---
<Author name={frontmatter.author}/>
<Biography client:visible>
{frontmatter.author} lebt in Toronto, Kanada
und fotografiert gerne.
</Biography>

Du kannst Markdown-Dateien direkt in deine Astro-Dateien importieren! F├╝r den Import einzelner Seiten verwendest du import und f├╝r mehrere Seiten Astro.glob().

---
// Importiere eine Markdown-Datei.
// Auch dynamischer import() wird unterst├╝tzt!
import * as tollerBeitrag from '../pages/post/toller-beitrag.md';
// Du kannst auch mehrere Markdown-Dateien
// mit Astro.glob importieren:
const posts = await Astro.glob('../pages/post/*.md');
---
Ein gro├čartiger Beitrag:
<a href={tollerBeitrag.url}>{tollerBeitrag.frontmatter.title}</a>
<ul>
{posts.map(post => <li>{post.frontmatter.title}</li>)}
</ul>

Du kannst optional einen Typ f├╝r die Variable frontmatter bereitstellen, indem du ein TypeScript-Generikum verwendest:

---
interface Frontmatter {
title: string;
description?: string;
}
const posts = await Astro.glob<Frontmatter>('../pages/post/*.md');
---
<ul>
{posts.map(post => <li>{post.title}</li>)}
<!-- post.title ist vom Typ `string`! -->
</ul>

Jede Markdown-Datei exportiert die folgenden Eigenschaften:

Enth├Ąlt alle Daten, die im YAML-Frontmatter dieser Datei angegeben sind.

Der absolute Pfad dieser Datei (z. B. /home/benutzer/projekte/.../datei.md).

Wenn es sich um eine Seite handelt, die URL der Seite (z. B. /de/guides/markdown-content/).

Eine asynchrone Funktion, die die ├ťberschriften der Markdown-Datei zur├╝ckgibt. Der R├╝ckgabewert folgt diesem Typ: { depth: number; slug: string; text: string }[].

Eine Funktion, die den unverarbeiteten Markdown-Quellcode (ohne den Frontmatter-Block) als String zur├╝ckgibt. Dies ist hilfreich, wenn du z. B. die Lesezeit eines Beitrags berechnen willst. Dieses Beispiel verwendet das beliebte Paket reading-time:

---
import readingTime from 'reading-time';
const posts = await Astro.glob('./posts/**/*.md');
---
{posts.map((post) => (
<Fragment>
<h2>{post.frontmatter.title}</h2>
<p>{readingTime(post.rawContent()).text}</p>
</Fragment>
))}

Eine asynchrone Funktion, die das Ergebnis der Umwandlung deines Markdown-Quellcodes zu Astro-Quellcode zur├╝ckgibt. Hinweis: An diesem Punkt wurden noch keine {JSX-Ausdr├╝cke}, <Komponenten /> oder Layouts verarbeitet! Nur Standard-Markdown-Bl├Âcke wie ## ├ťberschriften und - Listen wurden in HTML umgewandelt. Dies ist z. B. n├╝tzlich, wenn du Zusammenfassungen f├╝r Blogbeitr├Ąge rendern willst. Da die Astro-Syntax g├╝ltiges HTML ist, k├Ânnen beliebte Bibliotheken wie node-html-parser eingesetzt werden, um den ersten Absatz des Beitrags abzufragen:

---
import { parse } from 'node-html-parser';
const posts = await Astro.glob('./posts/**/*.md');
---
{posts.map(async (post) => {
const firstParagraph = parse(await post.compiledContent())
.querySelector('p:first-of-type');
return (
<Fragment>
<h2>{post.frontmatter.title}</h2>
{firstParagraph ? <p>{firstParagraph.innerText}</p> : null}
</Fragment>
);
})}

Eine Komponente, die den vollst├Ąndigen gerenderten Inhalt der Markdown-Datei zur├╝ckgibt. Hier ein Beispiel:

---
import {Content as PromoBanner} from '../components/promoBanner.md';
---
<h2>Heutige Sonderaktion</h2>
<PromoBanner />

Wenn du getStaticPaths und Astro.glob() verwendest, um Seiten aus Markdown-Dateien zu generieren, kannst du props verwenden, um die <Content/>-Komponente an die generierte Seite zu ├╝bergeben. Anschlie├čend kannst du die Komponente aus Astro.props abrufen und in deiner Vorlage rendern.

---
export async function getStaticPaths() {
const posts = await Astro.glob('../posts/**/*.md')
return posts.map(post => ({
params: {
slug: post.frontmatter.slug
},
props: {
post
},
}))
}
const { Content } = Astro.props.post
---
<article>
<Content/>
</article>

Du kannst Astros integrierte Markdown-Komponente in dein Komponentenskript importieren und dann beliebigen Markdown-Code zwischen die Tags <Markdown></Markdown> schreiben.

---
import { Markdown } from 'astro/components';
import Layout from '../layouts/Layout.astro';
const expressions = 'Lorem ipsum';
---
<Layout>
<Markdown>
# Hallo Welt!
**Alles**, was in einer `.md`-Datei unterst├╝tzt wird,
wird auch hier unterst├╝tzt!
Es gibt _null_ Laufzeit-Overhead.
Dar├╝ber hinaus unterst├╝tzt Astro:
- Astro-{Ausdr├╝cke}
- Automatische Normalisierung der Einr├╝ckung
- Automatisches Vermeiden der Verarbeitung
von Ausdr├╝cken in Codebl├Âcken
```js
// Dieser Inhalt wird nicht transformiert!
const object = { someOtherValue };
```
- Umfangreiche Komponentenunterst├╝tzung
wie in jeder `.astro`-Datei!
- Rekursive Markdown-Unterst├╝tzung (innerhalb von
Komponenten verschachtelter Markdown-Code
wird ebenfalls verarbeitet)
</Markdown>
</Layout>

Falls du Markdown-Inhalt aus einer externen Quelle geladen hast, kannst du diesen ├╝ber das content-Attribut direkt an die Markdown-Komponente ├╝bergeben.

---
import { Markdown } from 'astro/components';
const content = await fetch('https://raw.githubusercontent.com/withastro/docs/main/README.md').then(res => res.text());
---
<Layout>
<Markdown content={content} />
</Layout>

<Markdown />-Komponenten k├Ânnen verschachtelt werden.

---
import { Markdown } from 'astro/components';
const content = await fetch('https://raw.githubusercontent.com/withastro/docs/main/README.md').then(res => res.text());
---
<Layout>
<Markdown>
## Markdown-Beispiel
Hier haben wir etwas __Markdown__-Code.
Wir k├Ânnen auch entfernte Inhalte dynamisch rendern.
<Markdown content={content} />
</Markdown>
</Layout>

Astros Markdown-Unterst├╝tzung basiert auf remark, einem leistungsstarken Werkzeug zum Parsen und Verarbeiten von Markdown mit einem aktiven ├ľkosystem. Andere Markdown-Parser wie Pandoc oder markdown-it werden derzeit nicht unterst├╝tzt.

├ťber die Datei astro.config.mjs kannst du anpassen, wie remark deinen Markdown-Code parsen soll. Lies unsere Konfigurationsreferenz┬á(EN) f├╝r eine vollst├Ąndige Liste aller Optionen, oder folge der untenstehenden Anleitung, um zu erfahren, wie du Plugins hinzuf├╝gen und die Syntaxhervorhebung anpassen kannst.

Die Markdown-Verarbeitung in Astro kann durch Drittanbieter-Plugins f├╝r remark und rehype erweitert werden. Du kannst deine Plugins in astro.config.mjs bereitstellen.

So f├╝gst du ein Markdown-Plugin zu Astro hinzu

Abschnitt betitelt So f├╝gst du ein Markdown-Plugin zu Astro hinzu
  1. Verwende deinen Paketmanager, um das NPM-Paket des Plugins zu deinem Projekt hinzuzuf├╝gen.

  2. Aktualisiere die Felder remarkPlugins oder rehypePlugins in Astros Konfigurationsoptionen:

    astro.config.mjs
    export default {
    markdown: {
    remarkPlugins: [
    // Hier kannst du Remark-Plugins zu deinem Projekt hinzuf├╝gen.
    // Falls du Optionen an ein Plugin ├╝bergeben musst,
    // verwende ein Array und ├╝bergib sie als zweites Element.
    // ['remark-autolink-headings', { behavior: 'prepend' }],
    ],
    rehypePlugins: [
    // Hier kannst du Rehype-Plugins zu deinem Projekt hinzuf├╝gen.
    // Falls du Optionen an ein Plugin ├╝bergeben musst,
    // verwende ein Array und ├╝bergib sie als zweites Element.
    // 'rehype-slug',
    // ['rehype-autolink-headings', { behavior: 'prepend' }],
    ],
    },
    };

    Du kannst Plugins entweder ├╝ber ihren Namen hinzuf├╝gen oder sie importieren:

    astro.config.mjs
    import autolinkHeadings from 'remark-autolink-headings';
    export default {
    markdown: {
    remarkPlugins: [[autolinkHeadings, { behavior: 'prepend' }]],
    },
    };

Astro unterst├╝tzt von Haus aus Shiki und Prism und erm├Âglicht so die Syntaxhervorhebung in folgenden Bereichen:

Shiki ist standardm├Ą├čig aktiviert und mit dem Design github-dark vorkonfiguriert. Die kompilierte Ausgabe wird auf Inline-Stile ohne ├╝berfl├╝ssige CSS-Klassen, Stylesheets oder clientseitigen JavaScript-Code beschr├Ąnkt.

Falls du dich f├╝r die Verwendung von Prism entscheidest, verwenden wir stattdessen die CSS-Klassen von Prism. Bitte beachte, dass du in diesem Fall dein eigenes CSS-Stylesheet mitbringen musst, damit die Syntaxhervorhebung angezeigt wird! Weitere Einzelheiten findest du im Abschnitt zur Prism-Konfiguration.

Shiki ist unsere Standard-Syntaxhervorhebung. Wenn du zu Prism wechseln oder die Syntaxhervorhebung vollst├Ąndig deaktivieren m├Âchtest, kannst du das Konfigurationsobjekt markdown verwenden:

astro.config.mjs
export default {
markdown: {
// Kann 'shiki' (Standard), 'prism' oder false sein,
// um die Hervorhebung ganz zu deaktivieren
syntaxHighlight: 'prism',
},
};

Wenn du Shiki verwendest, kannst du alle Optionen wie folgt ├╝ber das Objekt shikiConfig konfigurieren:

astro.config.mjs
export default {
markdown: {
shikiConfig: {
// W├Ąhle eines der von Shiki mitgelieferten Themen,
// oder f├╝ge dein eigenes hinzu. Mehr dazu hier:
// https://github.com/shikijs/shiki/blob/main/docs/themes.md
theme: 'dracula',
// F├╝ge eigene Sprachen hinzu.
// Hinweis: Shiki hat unz├Ąhlige Sprachen direkt eingebaut,
// einschlie├člich .astro! Mehr dazu hier:
// https://github.com/shikijs/shiki/blob/main/docs/languages.md
langs: [],
// Aktiviere automatische Zeilenumbr├╝che,
// um horizontales Scrollen zu vermeiden
wrap: true,
},
},
};

Wir empfehlen dir auch, bei Gelegenheit in Shikis Theme-Dokumentation einzutauchen, um mehr ├╝ber das Laden von benutzerdefinierten Themen, das Umschalten zwischen Hell- und Dunkelmodus oder das Styling ├╝ber CSS-Variablen zu erfahren.

Wenn du Prism verwenden willst, musst du ein Stylesheet zur Syntaxhervorhebung zu deinem Projekt hinzuf├╝gen. Wenn du gerade erst anf├Ąngst und Prism gegen├╝ber Shiki bevorzugst, empfehlen wir dir folgende Vorgehensweise:

  1. Stelle syntaxHighlight: 'prism' in deiner Astro-Konfigurationsdatei ein.
  2. W├Ąhle ein vorgefertigtes Stylesheet auf Prism Themes aus und lade es herunter.
  3. F├╝ge dieses Stylesheet in das public/-Verzeichnis deines Projekts ein.
  4. Lade es im <head>-Abschnitt deiner Seite mit einem <link>-Tag.

Du kannst auch die Liste der von Prism unterst├╝tzten Sprachen besuchen, um mehr ├╝ber die Optionen und deren Verwendung zu erfahren.