Diese Anleitung führt dich durch die Einrichtung von shipyard in deinem Astro-Projekt. Am Ende hast du eine vollständig konfigurierte Seite mit Dokumentations- und Blog-Funktionalität.
Bevor du beginnst, stelle sicher dass du hast:
npm create astro@latestInstalliere die shipyard-Pakete die du brauchst:
# Vollausgestattete Seite (Doku + Blog)
npm install @levino/shipyard-base @levino/shipyard-docs @levino/shipyard-blog
# Nur Dokumentationsseite
npm install @levino/shipyard-base @levino/shipyard-docs
# Nur Blog-Seite
npm install @levino/shipyard-base @levino/shipyard-blog
# Nur Kern-Komponenten
npm install @levino/shipyard-baseshipyard benötigt folgende Peer Dependencies:
npm install tailwindcss daisyui @tailwindcss/typographyBevor wir in die Konfigurationsdetails eintauchen, hier eine kurze Checkliste der Dateien, die du erstellen oder ändern musst:
| Datei | Zweck | Erforderlich? |
|---|---|---|
astro.config.mjs | Astro-Integrationen und Seiten-Einstellungen | Ja |
src/styles/app.css | Tailwind CSS 4 Setup mit @source-Direktiven | Ja |
src/content.config.ts | Content Collection Schemas und Loader | Ja |
docs/ Verzeichnis | Dokumentations-Markdown-Dateien | Ja (für Doku) |
blog/ Verzeichnis | Blog-Beitrags-Markdown-Dateien | Ja (für Blog) |
Die am häufigsten vergessene Datei ist src/content.config.ts — ohne sie erhältst du Fehler wie “The collection does not exist” beim Bauen deiner Seite.
Erstelle src/styles/app.css mit der Tailwind CSS 4 Konfiguration:
/* Tailwind CSS 4 Setup */
@import "tailwindcss";
/* Importiere shipyard-Pakete - enthält sowohl Styles als auch @source-Direktiven */
@import "@levino/shipyard-base";
@import "@levino/shipyard-blog";
@import "@levino/shipyard-docs";
@plugin "daisyui";
@plugin "@tailwindcss/typography";Wichtig: Die shipyard-Pakete enthalten automatisch die nötigen @source-Direktiven, damit Tailwind die CSS-Klassen in den Komponenten erkennt. Siehe Tailwind CSS Setup für detaillierte Konfigurationsoptionen und Fehlerbehebung.
Aktualisiere deine astro.config.mjs:
import shipyard from '@levino/shipyard-base'
import shipyardDocs from '@levino/shipyard-docs'
import shipyardBlog from '@levino/shipyard-blog'
import { defineConfig } from 'astro/config'
// Importiere deine CSS-Datei mit ?url
import appCss from './src/styles/app.css?url'
export default defineConfig({
integrations: [
shipyard({
css: appCss, // Erforderlich: übergib dein CSS an shipyard
brand: 'Meine Seite',
title: 'Meine tolle Seite',
tagline: 'Erstellt mit shipyard',
navigation: {
docs: { label: 'Doku', href: '/docs' },
blog: { label: 'Blog', href: '/blog' },
},
}),
shipyardDocs(),
shipyardBlog(),
],
})Wichtige Konfigurationshinweise:
| Einstellung | Warum sie benötigt wird |
|---|---|
css: appCss | Übergibt dein Tailwind CSS Setup an shipyard. Ohne dies werden keine Styles angewendet. |
?url Import | Weist Vite an, den Dateipfad zur Build-Zeit aufzulösen für korrekte CSS-Verarbeitung. |
Erstelle src/content.config.ts — diese Datei ist essentiell, damit shipyard deine Dokumentations- und Blog-Inhalte finden und rendern kann:
import { defineCollection } from 'astro:content'
import { createDocsCollection } from '@levino/shipyard-docs'
import { blogSchema } from '@levino/shipyard-blog'
import { glob } from 'astro/loaders'
const docs = defineCollection(createDocsCollection('./docs'))
const blog = defineCollection({
schema: blogSchema,
loader: glob({ pattern: '**/*.md', base: './blog' }),
})
export const collections = { docs, blog }Nach der Einrichtung sollte dein Projekt so aussehen:
meine-seite/
├── docs/ # Dokumentations-Markdown-Dateien
│ ├── index.md # Doku-Startseite
│ └── getting-started.md # Dokumentationsseiten
├── blog/ # Blog-Beitrags-Markdown-Dateien
│ └── 2025-01-15-erster-beitrag.md
├── src/
│ ├── content.config.ts # Content Collection Konfiguration
│ ├── styles/
│ │ └── app.css # Tailwind CSS 4 Setup
│ └── pages/ # Zusätzliche Seiten
│ └── index.astro # Startseite
├── astro.config.mjs
└── package.jsonErstelle Markdown-Dateien im docs/-Verzeichnis:
---
title: Einführung
sidebar:
position: 1
description: Lerne unser Projekt kennen
---
# Einführung
Dein Dokumentationsinhalt hier...Wichtige Frontmatter-Optionen:
| Feld | Typ | Beschreibung |
|---|---|---|
title | string | Seitentitel |
sidebar.position | number | Position in Sidebar (niedriger = früher) |
description | string | Seitenbeschreibung für SEO |
Siehe @levino/shipyard-docs für alle Frontmatter-Optionen.
Erstelle Markdown-Dateien im blog/-Verzeichnis:
---
title: Mein erster Beitrag
description: Eine kurze Beschreibung dieses Beitrags
date: 2025-01-15
---
# Mein erster Beitrag
Dein Blog-Beitragsinhalt hier...Erforderliches Frontmatter:
| Feld | Typ | Beschreibung |
|---|---|---|
title | string | Beitragstitel |
description | string | Beitragsbeschreibung/Auszug |
date | Date | Veröffentlichungsdatum (YYYY-MM-DD) |
Siehe @levino/shipyard-blog für alle Frontmatter-Optionen.
Für eigenständige Seiten, die nicht Teil von Docs oder Blog Collections sind, verwende die Layouts von shipyard direkt.
Markdown-Seiten – Verwende das Markdown-Layout für Seiten mit Prosa-Styling:
---
layout: '@levino/shipyard-base/layouts/Markdown.astro'
title: Über uns
description: Erfahre mehr über unser Team
---
# Über uns
Dein Markdown-Inhalt mit schönem Typografie-Styling...Astro-Komponenten-Seiten – Importiere das Page-Layout für volle Kontrolle:
---
// src/pages/index.astro
import { Page } from '@levino/shipyard-base/layouts'
---
<Page title="Startseite" description="Willkommen auf unserer Seite">
<div class="hero min-h-[60vh] bg-base-200">
<div class="hero-content text-center">
<h1 class="text-5xl font-bold">Willkommen!</h1>
<p>Dein benutzerdefinierter Startseiten-Inhalt...</p>
</div>
</div>
</Page>Landing Pages – Verwende das Splash-Layout für zentrierten Inhalt ohne Prosa-Styling:
---
layout: '@levino/shipyard-base/layouts/Splash.astro'
title: Willkommen
---
<div class="hero min-h-screen">
<h1 class="text-5xl font-bold">Meine Landing Page</h1>
</div>Siehe @levino/shipyard-base Layouts für alle verfügbaren Layouts und Optionen.
shipyard unterstützt Astros i18n-Features. Aktualisiere deine Astro-Konfiguration:
export default defineConfig({
i18n: {
defaultLocale: 'de',
locales: ['de', 'en', 'fr'],
routing: {
prefixDefaultLocale: true,
},
},
integrations: [
// ... deine Integrationen
],
})Organisiere Inhalte nach Locale:
docs/
├── de/
│ ├── index.md
│ └── getting-started.md
├── en/
│ ├── index.md
│ └── getting-started.md
blog/
├── de/
│ └── 2025-01-15-erster-beitrag.md
├── en/
│ └── 2025-01-15-first-post.mdStarte den Entwicklungsserver:
npm run devFür Produktion bauen:
npm run buildshipyard besteht aus drei Paketen, die zusammenarbeiten:
| Paket | Zweck | Dokumentation |
|---|---|---|
@levino/shipyard-base | Kern-Layouts, Komponenten und Konfiguration | Base Package |
@levino/shipyard-docs | Dokumentations-Features, Sidebar, Paginierung | Docs Package |
@levino/shipyard-blog | Blog-Funktionalität, Beitragsliste, Navigation | Blog Package |
Jetzt wo du shipyard eingerichtet hast, erkunde diese Themen:
The collection "docs" does not exist or is empty.
Cannot read properties of undefined (reading 'render')Ursache: Fehlende oder falsch konfigurierte src/content.config.ts Datei.
Lösung: Erstelle die Content-Config-Datei wie oben in Content Collections gezeigt. Stelle sicher:
src/content.config.ts (nicht im Root-Verzeichnis)collections Objekt mit deinen definierten Collectionsdocs für Dokumentation, blog für Blog-Beiträge)Wenn du sofort nach der Installation TypeScript- oder Build-Fehler siehst:
Prüfe Peer Dependencies — Stelle sicher, dass alle erforderlichen Peer Dependencies installiert sind:
npm install tailwindcss daisyui @tailwindcss/typographyÜberprüfe CSS-Setup — Stelle sicher, dass src/styles/app.css existiert und die shipyard-Pakete mit @import importiert
Prüfe css-Konfiguration — Stelle sicher, dass du css: appCss an die shipyard-Integration übergibst
Wenn Komponenten ungestylt oder kaputt erscheinen:
Prüfe CSS-Imports — Stelle sicher, dass alle benötigten shipyard-Pakete in deiner app.css importiert werden
Überprüfe CSS-Import-Reihenfolge — In deiner app.css muss @import "tailwindcss" vor den shipyard-Paket-Imports kommen
Prüfe css-Konfiguration — Stelle sicher, dass astro.config.mjs dein CSS mit ?url importiert und an shipyard übergibt
Siehe Tailwind CSS Setup für detaillierte Fehlerbehebung.
docs/ im Projekt-Root sein, nicht in src/docs/'./docs')docs/index.md)