Communitygithub.com

khaym/stitch-to-astro

Verfahren zum Erstellen von Seiten mit Astro Content Collections und dynamischem Routing basierend auf Stitch-Designs.

Was ist stitch-to-astro?

Dieses Skill definiert einen schrittweisen Arbeitsablauf zum Erstellen inhaltsgesteuerter Seiten mit Astro 5 Content Collections (Content Layer API) und dynamischem Routing. Es beschreibt detailliert die Erstellung von Schemata, die Handhabung von MDX-Inhalten mit frontmatter, die Implementierung dynamischer Routen und die Erstellung von Seitenkomponenten. Nützlich ist es für Entwickler, die statische oder dynamische Webseiten aus Strukturdesigns wie Stitch generieren, da es den Prozess von der Schema-Definition über die Inhaltserstellung bis hin zur Build-Überprüfung automatisiert. Das Skill behandelt spezifische Fallstricke wie YAML-Konvertierungen und bietet eine Checkliste für die vollständige Implementierung. Es ist für die Verwendung mit Astro 5 konzipiert und setzt die Abhängigkeit von globalen CSS-Design-Token sowie einer Stitch-Referenzdatei voraus.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/khaym/stitch-to-astro/tree/HEAD/.claude/skills/page-procedure

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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.css mit Design-Token vorhanden (erstellt durch css-procedure)
  • docs/stitch/reference.md vorhanden (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 in public/)
  • Bilder, die größer als 2560px sind, vor dem Committen verkleinern
  • Bei Verwendung des image()-Helpers im Schema werden Bildpfade im Frontmatter in den Typ ImageMetadata aufgelöst. ImageMetadata auch 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; getStaticPaths generiert statische Pfade
  • render() gibt den MDX-Text als Content-Komponente zurück
  • item.data bietet 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>

MethodeVerwendungBeispiel
<Picture>Statische Bilder, die zur Build-Zeit bekannt sindHero-Hintergründe, Eintragsbilder
<img>Bilder, die dynamisch durch clientseitiges JS ausgetauscht werdenDiashows 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:

AnforderungImplementierung
Semantikrole="dialog" + aria-modal="true" + aria-label
Öffnen/Schließenhidden-Attribut umschalten + CSS opacity-Übergang
BildlaufsperreOffen: document.body.style.overflow = "hidden" / Geschlossen: auf """ zurücksetzen
TastaturEscape zum Schließen, Pfeiltasten zur Navigation
FokusfalleTab/Umschalt+Tab durchläuft Schaltflächen innerhalb des Modals
Fokuswiederherstellungfocus() auf Auslöseelement beim Schließen
Hintergrund schließenSchließen, wenn Klickziel kein interaktives Element ist
z-indexHö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

FehlerUrsacheBehebung
Expected type "string", received "object"YAML hat einen Wert automatisch konvertiert (Monatsname → Date etc.)Wert in Anführungszeichen setzen
Could not find imageFalscher BildpfadRelativen Pfad zur MDX-Datei überprüfen
does not match collection schemaFehlendes Feld oder Typkonflikt im FrontmatterGegen 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.ts enthält ein definiertes Schema
  • MDX-Frontmatter entspricht dem Schema
  • Bilder befinden sich in src/content/ und wurden auf ≤2560px verkleinert
  • [...slug].astro gibt alle Einträge von getStaticPaths zurück
  • Optionale Feldabschnitte verwenden bedingte Wiedergabe
  • npm run build ist erfolgreich
  • Visuelle Bestätigung im Browser für alle Abschnitte (auch in mobiler Breite)

Verwandte Skills