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/typography @astrojs/tailwindBevor 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 |
tailwind.config.mjs | Tailwind CSS Konfiguration | 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.
Aktualisiere deine astro.config.mjs:
import tailwind from '@astrojs/tailwind'
import shipyard from '@levino/shipyard-base'
import shipyardDocs from '@levino/shipyard-docs'
import shipyardBlog from '@levino/shipyard-blog'
import { defineConfig } from 'astro/config'
export default defineConfig({
integrations: [
tailwind({ applyBaseStyles: false }),
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 |
|---|---|
tailwind({ applyBaseStyles: false }) | Verhindert Konflikte zwischen Tailwinds Basis-Styles und DaisyUI. Ohne diese Einstellung können Komponenten ungestylt oder fehlerhaft erscheinen. |
| Integrations-Reihenfolge | Tailwind muss vor den shipyard-Integrationen kommen, damit Styles korrekt verarbeitet werden. |
Erstelle oder aktualisiere tailwind.config.mjs:
import daisyui from 'daisyui'
import typography from '@tailwindcss/typography'
/** @type {import('tailwindcss').Config} */
export default {
content: [
'./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}',
'./docs/**/*.md',
'./blog/**/*.md',
'node_modules/@levino/shipyard-*/**/*.{astro,js,ts}',
],
theme: {
extend: {},
},
plugins: [typography, daisyui],
}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
│ └── pages/ # Zusätzliche Seiten
│ └── index.astro # Startseite
├── astro.config.mjs
├── tailwind.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 @astrojs/tailwindÜberprüfe Tailwind-Konfiguration — Stelle sicher, dass tailwind.config.mjs die shipyard-Pakete im content-Array enthält
Prüfe Integrations-Reihenfolge — In astro.config.mjs muss Tailwind vor den shipyard-Integrationen kommen
Wenn Komponenten ungestylt oder kaputt erscheinen:
Prüfe applyBaseStyles — Stelle sicher, dass Tailwind mit applyBaseStyles: false konfiguriert ist:
tailwind({ applyBaseStyles: false })Überprüfe Content-Pfade — Stelle sicher, dass tailwind.config.mjs Pfade zu shipyard-Paketen und deinen Content-Verzeichnissen enthält
docs/ im Projekt-Root sein, nicht in src/docs/'./docs')docs/index.md)