Verfahren für Inhaltsseiten
Schritt-für-Schritt-Verfahren zum Erstellen inhaltsgesteuerter Seiten mit Astro Content Collections (Content Layer API) und dynamischem Routing.
Voraussetzungen
src/styles/global.cssmit Design-Token vorhanden (erstellt durch css-procedure)docs/stitch/reference.mdvorhanden (Feldinformationen aus Stitch-Bildschirmen)
Ein- / Ausgabe
[Eingabe] [Ausgabe]
docs/stitch/reference.md ──┐
(Bildschirmfeldinfo) │
progress.md Notizen ─────────┼──→ src/content/config.ts (Schema)
(Abschnittsstruktur, │ src/content/<collection>/<slug>/index.mdx (Daten)
Designentscheidungen) │ src/pages/<collection>/[...slug].astro (Routing)
│ src/components/*.astro (Abschnittskomponenten)
Schritte
Schritt 1: Schema-Definition (src/content/config.ts)
Die Astro 5 Content Layer API verwendet den glob-Loader.
1-1. Collection definieren
import { defineCollection, z } from "astro:content";
import { glob } from "astro/loaders";
const myCollection = defineCollection({
loader: glob({ pattern: "**/index.mdx", base: "./src/content/my-collection" }),
schema: ({ image }) =>
z.object({
title: z.string(),
// ... Felder definieren
heroImage: image(), // image()-Helfer für Bilder verwenden
}),
});
export const collections = { myCollection };
1-2. Schema-Design-Richtlinien
- Minimal starten, schrittweise erweitern. Nur Felder definieren, die für die aktuelle Seitenwiedergabe benötigt werden; bei der Implementierung von Komponenten weitere hinzufügen
image()-Helfer für Bildfelder verwenden, um Pfadvalidierung und Optimierung zur Build-Zeit zu ermöglichen.optional()für Felder verwenden, die nicht in jedem Eintrag benötigt werden- Optionale Arrays für Abschnittsdaten verwenden, um die Sichtbarkeit von Abschnitten pro Seite zu steuern:
// Schema moments: z.array(z.object({ title: z.string(), ... })).optional()<!-- Seitenvorlage: Bedingte Wiedergabe --> {data.moments && <MomentsSection moments={data.moments} />}
1-3. YAML-Frontmatter-Fallstricke
- Monatsnamen (März, Mai etc.) und Ja/Nein werden von YAML automatisch konvertiert. In Anführungszeichen setzen, wenn sie als Strings behandelt werden sollen:
date: "März" - Bildpfade sind relativ zur MDX-Datei:
heroImage: ./hero.jpg
Schritt 2: Inhaltsdaten erstellen
2-1. Verzeichnisstruktur
src/content/<collection>/<slug>/
├── index.mdx # Frontmatter + MDX-Text
├── hero.jpg # Bilder, die zusammen mit dem Inhalt abgelegt werden
└── ...
2-2. MDX-Dateistruktur
---
title: "Seitentitel"
heroImage: ./hero.jpg
description: "Beschreibungstext"
---
## MDX-Text
Der Text wird über `render()` abgerufen und als `<Content />` gerendert.
2-3. Bildverwaltung
- Bilder innerhalb von
src/content/ablegen, zusammen mit ihrem Inhalt (nicht inpublic/) - Bilder, die größer als 2560px sind, vor dem Committen verkleinern
- Bei Verwendung des
image()-Helpers im Schema werden Bildpfade im Frontmatter in den TypImageMetadataaufgelöst.ImageMetadataauch in Komponenten-Props verwenden
Schritt 3: Dynamische Routing-Seite
Erstelle src/pages/<collection>/[...slug].astro:
---
import type { GetStaticPaths } from "astro";
import { getCollection, render } from "astro:content";
export const getStaticPaths = (async () => {
const items = await getCollection("myCollection");
return items.map((item) => ({
params: { slug: item.id },
props: { item },
}));
}) satisfies GetStaticPaths;
const { item } = Astro.props;
const { Content } = await render(item);
---
Wichtige Punkte
getCollection()ruft alle Einträge ab;getStaticPathsgeneriert statische Pfaderender()gibt den MDX-Text alsContent-Komponente zurückitem.databietet typsicheren Zugriff auf Frontmatter-Felder- Bedingte Wiedergabe für optionale Felder:
{data.field && <Component ... />}
Schritt 4: Seitendatendateien (src/data/<page>.md)
Benutzerbearbeitbare Inhalte (Text, Labels, URLs) für jede Seite sollten in Markdown-Dateien mit YAML-Frontmatter unter src/data/ definiert werden. Dies hält das Format konsistent mit Content Collections und erleichtert Benutzern das Auffinden und Bearbeiten ihrer Inhalte.
Hinweis: Das Verzeichnis
src/data/wird nicht durch das Scaffold-Skill erstellt. Erstelle es in diesem Schritt.
4-1. Für jede Seite eine Datendatei erstellen
src/data/
├── index.md # Inhalt der Startseite (oben)
├── about.md # Inhalt der "Über mich"-Seite
└── skills.md # Inhalt der Fähigkeiten-Seite
4-2. Bearbeitbare Inhalte als YAML-Frontmatter definieren
---
# ==============================
# Inhalt der Startseite
# Bearbeite diese Datei, um deine Seite anzupassen.
# ==============================
hero:
headingPrefix: "Hallo, ich bin ein"
highlightedText: "Webentwickler."
description: "Ich entwickle skalierbare, benutzerzentrierte Anwendungen..."
badgeText: "Verfügbar für neue Projekte"
cta:
heading: "Bereit, gemeinsam etwas zu bauen?"
description: "Ich bin derzeit offen für freiberufliche Möglichkeiten..."
buttons:
- label: "Kontakt aufnehmen"
href: "mailto:[email protected]"
variant: "primary"
- label: "Lebenslauf herunterladen"
href: "#"
variant: "secondary"
---
- Nur benutzerbearbeitbare Texte in das YAML aufnehmen (Strings, Labels, URLs, Arrays von Text)
- Nicht bearbeitbare Daten (SVG-Icon-Pfade etc.) als TypeScript-Konstanten in der
.astro-Seitendatei belassen
4-3. Daten in der Seite importieren
import.meta.glob() verwenden, um das Frontmatter zu laden:
---
const content = Object.values(
import.meta.glob("../data/index.md", { eager: true })
)[0] as { frontmatter: Record<string, unknown> };
const { hero, cta } = content.frontmatter;
---
Schritt 5: Implementierung von Abschnittskomponenten
Jeden Abschnitt (Hero, Moments etc.) als unabhängige Komponente in src/components/ erstellen.
Die Entwicklungsrichtlinie für Komponentenstruktur und CSS-Regeln befolgen.
Bildanzeige: <Picture> vs <img>
| Methode | Verwendung | Beispiel |
|---|---|---|
<Picture> | Statische Bilder, die zur Build-Zeit bekannt sind | Hero-Hintergründe, Eintragsbilder |
<img> | Bilder, die dynamisch durch clientseitiges JS ausgetauscht werden | Diashows in modalen Galerien |
<Picture> wird zur Build-Zeit gerendert, daher kann es nicht verwendet werden, wenn src durch clientseitiges JS ausgetauscht wird.
Clientseitiges JavaScript
<script>-Tags in Astro-Komponenten werden als clientseitiges JS ausgeführt. Interaktive Funktionen können ohne Frameworks (React etc.) erstellt werden.
Datenweitergabemuster: data-*-Attribute verwenden, um Frontmatter-Daten an clientseitiges JS zu übergeben. <script> kann nicht direkt auf Frontmatter-Variablen verweisen.
Barrierefreiheit: Modal / Overlay
Checkliste für die Implementierung modaler Dialoge:
| Anforderung | Implementierung |
|---|---|
| Semantik | role="dialog" + aria-modal="true" + aria-label |
| Öffnen/Schließen | hidden-Attribut umschalten + CSS opacity-Übergang |
| Bildlaufsperre | Offen: document.body.style.overflow = "hidden" / Geschlossen: auf """ zurücksetzen |
| Tastatur | Escape zum Schließen, Pfeiltasten zur Navigation |
| Fokusfalle | Tab/Umschalt+Tab durchläuft Schaltflächen innerhalb des Modals |
| Fokuswiederherstellung | focus() auf Auslöseelement beim Schließen |
| Hintergrund schließen | Schließen, wenn Klickziel kein interaktives Element ist |
| z-index | Höher als vorhandene feste Elemente (z. B. Header 50 → Modal 60) |
Schritt 6: Build-Überprüfung
npm run build
Fehler der Content Collections-Schemavalidierung treten zur Build-Zeit mit klaren Meldungen auf.
Häufige Fehler
| Fehler | Ursache | Behebung |
|---|---|---|
Expected type "string", received "object" | YAML hat einen Wert automatisch konvertiert (Monatsname → Date etc.) | Wert in Anführungszeichen setzen |
Could not find image | Falscher Bildpfad | Relativen Pfad zur MDX-Datei überprüfen |
does not match collection schema | Fehlendes Feld oder Typkonflikt im Frontmatter | Gegen das Schema in config.ts prüfen |
Schritt 7: Dev-Server-Überprüfung
npm run dev
- Schema-Änderungen können einen Neustart des Dev-Servers erfordern (Löschen des Content-Stores)
- Wenn Fehler nach dem Neustart bestehen bleiben, das
.astro/-Verzeichnis löschen und neu starten
Checkliste
-
src/content/config.tsenthält ein definiertes Schema - MDX-Frontmatter entspricht dem Schema
- Bilder befinden sich in
src/content/und wurden auf ≤2560px verkleinert -
[...slug].astrogibt alle Einträge vongetStaticPathszurück - Optionale Feldabschnitte verwenden bedingte Wiedergabe
-
npm run buildist erfolgreich - Visuelle Bestätigung im Browser für alle Abschnitte (auch in mobiler Breite)