@levino/shipyard-base

@levino/shipyard-base

Das Base-Paket ist das Fundament von shipyard. Es bietet das Kern-Konfigurationssystem und Layouts, die deine Seite antreiben.

Installation

npm install @levino/shipyard-base

Peer Dependencies

npm install tailwindcss daisyui @tailwindcss/typography

Paket	Version
`astro`	^7.2.4
`tailwindcss`	^4
`daisyui`	^5
`@tailwindcss/typography`	^0.5.20

Tailwind-Konfiguration

shipyard verwendet Tailwind CSS 4, das einen CSS-basierten Konfigurationsansatz nutzt. Für detaillierte Setup-Anweisungen siehe die Tailwind CSS Setup-Anleitung.

Konfiguration

Füge die shipyard-Integration zu deiner astro.config.mjs hinzu:

import shipyard from '@levino/shipyard-base'
import { defineConfig } from 'astro/config'

export default defineConfig({
  integrations: [
    shipyard({
      brand: 'Meine Seite',
      title: 'Meine tolle Seite',
      tagline: 'Erstellt mit shipyard',
      navigation: {
        docs: { label: 'Dokumentation', href: '/docs' },
        blog: { label: 'Blog', href: '/blog' },
      },
    }),
  ],
})

Konfigurationsoptionen

Option	Typ	Erforderlich	Standard	Beschreibung
`brand`	`string`	Ja	—	Markenname in Navigationsleiste und Sidebar
`title`	`string`	Ja	—	Seitentitel im HTML `<title>` Tag
`tagline`	`string`	Ja	—	Kurze Beschreibung deiner Seite
`navigation`	`NavigationTree`	Ja	—	Globale Navigationsstruktur (siehe unten)
`scripts`	`Script[]`	Nein	`[]`	Skripte im Seitenkopf
`footer`	`FooterConfig`	Nein	—	Footer-Konfiguration (Links, Copyright, Stil)
`hideBranding`	`boolean`	Nein	`false`	“Built with Shipyard” Branding ausblenden
`defaultImage`	`string`	Nein	—	Fallback-Vorschaubild (URL oder `/Pfad` in `public/`) für Seiten ohne eigenes `image:`. Wird unverändert weitergereicht — nicht optimiert (Config-Importe können nicht durch Astros Bildpipeline laufen)
`locale`	`string`	Nein	—	Sprache der Seite, wenn Astros `i18n`-Routing nicht konfiguriert ist (z. B. `'de'`). Setzt `<html lang>` und shipyards eingebaute Beschriftungen wie „Auf dieser Seite“, „Weiter“ oder „Diese Seite bearbeiten“. Englisch und Deutsch sind eingebaut, andere Sprachen fallen auf Englisch zurück. Mit konfiguriertem `i18n` gilt die Sprache der jeweiligen Seite
`skipToContentLabel`	`string`	Nein	Eingebaute Beschriftung	Überschreibt die Beschriftung des „Zum Inhalt springen“-Links
`onBrokenLinks`	`'ignore' \| 'log' \| 'warn' \| 'throw'`	Nein	`'warn'`	Verhalten bei defekten internen Links während des Builds

Navigationsstruktur

Die navigation-Option definiert die Hauptnavigation deiner Seite. Jeder Eintrag kann haben:

Eigenschaft	Typ	Erforderlich	Standard	Beschreibung
`label`	`string`	Nein	Key-Name	Anzeigetext in Navigation
`href`	`string`	Nein	—	Link-Ziel-URL
`subEntry`	`NavigationTree`	Nein	—	Verschachtelte Einträge für Dropdown-Menüs

Einfache Navigation:

navigation: {
  docs: { label: 'Doku', href: '/docs' },
  blog: { label: 'Blog', href: '/blog' },
  about: { label: 'Über uns', href: '/about' },
}

Verschachtelte Navigation mit Dropdowns:

navigation: {
  docs: {
    label: 'Dokumentation',
    subEntry: {
      'getting-started': { label: 'Erste Schritte', href: '/docs/getting-started' },
      'api-reference': { label: 'API-Referenz', href: '/docs/api' },
    },
  },
  blog: { label: 'Blog', href: '/blog' },
}

Skripte hinzufügen

Füge Analytics oder andere Skripte zu jeder Seite hinzu:

shipyard({
  // ... andere Optionen
  scripts: [
    'https://example.com/analytics.js',
    { src: 'https://example.com/script.js', async: true },
  ],
})

Passe den Footer deiner Seite mit Links, Copyright-Hinweis und Styling an. Shipyard unterstützt sowohl einfache (einzeilige) als auch mehrspaltige Footer-Layouts, ähnlich wie Docusaurus.

Ein einfacher Footer zeigt Links in einer horizontalen Zeile:

shipyard({
  // ... andere Optionen
  footer: {
    links: [
      { label: 'Dokumentation', to: '/docs' },
      { label: 'Blog', to: '/blog' },
      { label: 'GitHub', href: 'https://github.com/myorg/myrepo' },
    ],
    copyright: 'Copyright © 2025 Meine Firma. Alle Rechte vorbehalten.',
  },
})

Für ein mehrspaltiges Layout verwende Objekte mit title und items:

shipyard({
  // ... andere Optionen
  footer: {
    style: 'dark',
    links: [
      {
        title: 'Doku',
        items: [
          { label: 'Erste Schritte', to: '/docs' },
          { label: 'API-Referenz', to: '/docs/api' },
        ],
      },
      {
        title: 'Community',
        items: [
          { label: 'Blog', to: '/blog' },
          { label: 'GitHub', href: 'https://github.com/myorg/myrepo' },
        ],
      },
    ],
    copyright: 'Copyright © 2025 Meine Firma.',
  },
})

Option	Typ	Standard	Beschreibung
`style`	`'light' \| 'dark'`	`'light'`	Footer-Farbthema
`links`	`(FooterLink \| FooterLinkColumn)[]`	`[]`	Footer-Links oder -Spalten
`copyright`	`string`	—	Copyright-Hinweis (unterstützt HTML)
`logo`	`FooterLogo`	—	Optionales Footer-Logo

FooterLink-Eigenschaften

Eigenschaft	Typ	Erforderlich	Beschreibung
`label`	`string`	Ja	Anzeigetext für den Link
`to`	`string`	Eines von `to`/`href`	Interner Link-Pfad (Locale-Präfix wird automatisch hinzugefügt)
`href`	`string`	Eines von `to`/`href`	Externe URL (öffnet in neuem Tab)

FooterLinkColumn-Eigenschaften

Eigenschaft	Typ	Erforderlich	Beschreibung
`title`	`string`	Ja	Spalten-Überschrift
`items`	`FooterLink[]`	Ja	Links innerhalb dieser Spalte

FooterLogo-Eigenschaften

Eigenschaft	Typ	Erforderlich	Beschreibung
`alt`	`string`	Ja	Alt-Text für das Logo
`src`	`string`	Ja	Logo-Bildquelle URL
`srcDark`	`string`	Nein	Optionales Dark-Mode-Logo
`href`	`string`	Nein	Link-URL beim Klick auf das Logo
`width`	`number`	Nein	Logo-Breite in Pixel
`height`	`number`	Nein	Logo-Höhe in Pixel

Shipyard-Branding

Standardmäßig zeigt der Footer einen “Built with Shipyard” Link. Um dieses Branding auszublenden:

shipyard({
  // ... andere Optionen
  hideBranding: true,
})

Layouts

shipyard bietet Layouts für deine Seiten.

Page Layout

Das Basis-Layout für alle Seiten. Enthält Navigationsleiste, optionale Sidebar und Footer. Verwende es für eigene Astro-Komponenten.

Verwendung in Astro:

---
import { Page } from '@levino/shipyard-base/layouts'
---

<Page title="Meine Seite" description="Seitenbeschreibung">
  <h1>Seiteninhalt</h1>
</Page>

Prop	Typ	Beschreibung
`title`	`string`	Seitentitel (kombiniert mit Seitentitel)
`description`	`string`	Seitenbeschreibung für SEO

Named Slots

Slot	Beschreibung
(default)	Seiteninhalt
`head`	Eigene Elemente im HTML `<head>`
`navbarExtra`	Zusätzlicher Inhalt in der Navigationsleiste
`sidebarExtra`	Zusätzlicher Inhalt in der Sidebar

Eigene Head-Elemente einfügen

Verwende den head-Slot, um eigene Meta-Tags, Open Graph-Daten, Canonical-URLs oder strukturierte Daten (JSON-LD) in den <head> einzufügen, ohne ein eigenes Layout bauen zu müssen:

---
import { Page } from '@levino/shipyard-base/layouts'
---

<Page title="Mein Event" description="Ein Community-Event">
  <meta slot="head" property="og:type" content="event" />
  <meta slot="head" property="og:image" content="/images/event.jpg" />
  <link slot="head" rel="canonical" href="https://example.com/mein-event" />
  <script slot="head" type="application/ld+json" set:html={JSON.stringify({
    "@context": "https://schema.org",
    "@type": "Event",
    "name": "Mein Event"
  })} />

  <h1>Mein Event</h1>
</Page>

Markdown Layout

Ein Layout mit Tailwind Typography (prose) Styling. Verwende es für eigenständige Markdown-Seiten.

---
layout: '@levino/shipyard-base/layouts/Markdown.astro'
title: Meine Seite
---

# Meine Seite

Dein Markdown-Inhalt mit schöner Typografie...

Splash Layout

Ein Layout mit zentriertem Inhalt aber ohne Prose-Styling. Ideal für Landing Pages mit eigenem Styling.

---
layout: '@levino/shipyard-base/layouts/Splash.astro'
title: Willkommen
---

<div class="hero">
  <h1>Willkommen auf meiner Seite</h1>
</div>

Soziale Vorschaubilder (OG / Twitter)

Shipyard erzeugt für jede Seite automatisch Meta-Tags für soziale Vorschauen (og:image, twitter:image usw.). Die Bildquelle ergibt sich aus dem image-Frontmatter-Feld der Seite, mit einem seitenweiten Fallback über defaultImage.

Frontmatter `image`

Content-Collections (Docs, Blog) erwarten einen relativen Pfad zu einem lokalen Bild. Astros image()-Schema-Helper validiert den Pfad und löst ihn beim Parsen in eine ImageMetadata-Referenz auf, sodass shipyard die Datei durch Astros Bildpipeline schicken kann:

---
title: Meine Seite
description: Eine kurze Zusammenfassung, die auch als og:image:alt verwendet wird
image: ./hero.jpg
---

Shipyard erzeugt eine 1200×630-JPEG-Variante — die von Facebook, LinkedIn und Twitter empfohlene Größe und klein genug (unter ~200 KB), damit Chat-Clients (WhatsApp, Telegram) die Vorschau tatsächlich abrufen. Das Bild wird zugeschnitten (fit: cover), sodass jedes Quellseitenverhältnis funktioniert, und EXIF-Daten (GPS, Gerät, Zeitstempel) werden beim erneuten Kodieren entfernt. Du kannst also ein Foto direkt aus deiner Handy-Kamera in den Content-Ordner legen — keine manuelle Optimierung oder Vorab-Zuschnitt nötig.

Absolute URLs (https://...) werden im Frontmatter von Content-Collections nicht mehr akzeptiert — sie umgehen die Bildpipeline und können daher nicht optimiert werden. Lege die Datei stattdessen neben deine Markdown-Datei.

Seitenweiter Standard

Setze defaultImage als Fallback für Seiten ohne eigenes image::

shipyard({
  brand: 'Meine Seite',
  title: 'Meine Seite',
  tagline: 'Mit shipyard gebaut',
  navigation: { /* ... */ },
  defaultImage: '/og-default.jpg',
})

Der Pfad kann ein gegen site aus astro.config.* aufgelöster /...-Pfad sein (z. B. eine Datei in public/) oder eine vollständige URL. Asset-Importe aus src/ funktionieren hier nicht — astro.config.* wird ausgeführt, bevor Vites Asset-Pipeline aktiv ist, das Bild wird also unverändert weitergereicht und nicht optimiert. Wenn du einen optimierten seitenweiten Standard möchtest, optimiere ihn vorab manuell (1200×630 JPEG, < 200 KB) und liefere ihn aus public/ aus. Seiten mit eigenem image: haben immer Vorrang und laufen durch die Content-Collection-Pipeline.

Erzeugte Meta-Tags

Für Seiten mit Bild gibt shipyard aus:

og:image (absolute URL — von den meisten Scrapern erwartet)
og:image:width und og:image:height
og:image:type (z. B. image/jpeg für optimierte Varianten)
og:image:alt (Standard: description der Seite)
twitter:card (summary_large_image)
twitter:image und twitter:image:alt

Defekte Link-Erkennung

Shipyard prüft während Produktions-Builds automatisch auf defekte interne Links. Dies hilft dir, Probleme zu erkennen, bevor du deine Seite veröffentlichst.

Konfiguration

Verwende die onBrokenLinks-Option, um zu steuern, was passiert, wenn defekte Links erkannt werden:

Wert	Verhalten
`'ignore'`	Nicht auf defekte Links prüfen
`'log'`	Defekte Links protokollieren, aber Build fortsetzen
`'warn'`	Warnungen für defekte Links protokollieren (Standard)
`'throw'`	Build bei defekten Links abbrechen

Beispiel - Build bei defekten Links abbrechen:

shipyard({
  brand: 'Meine Seite',
  title: 'Meine Seite',
  tagline: 'Erstellt mit shipyard',
  navigation: { /* ... */ },
  onBrokenLinks: 'throw',
})

Was geprüft wird

Interne Links die mit / beginnen (z.B. /docs/getting-started)
Links mit Query-Strings und Hash-Fragmenten (der Basispfad wird validiert)
Links zu HTML-Seiten, Verzeichnissen mit index.html und Asset-Dateien

Was ignoriert wird

Externe URLs (https://, http://)
Anker-Links (#section)
Spezielle Protokolle (mailto:, tel:, javascript:, data:)

Internationalisierung

Navigationslinks erhalten automatisch Locale-Präfixe wenn Astros i18n konfiguriert ist:

export default defineConfig({
  i18n: {
    defaultLocale: 'de',
    locales: ['de', 'en'],
    routing: { prefixDefaultLocale: true },
  },
  integrations: [shipyard({ /* ... */ })],
})

@levino/shipyard-base

Installation

Peer Dependencies

Tailwind-Konfiguration

Konfiguration

Konfigurationsoptionen

Navigationsstruktur

Skripte hinzufügen

Footer-Konfiguration

Einfacher Footer

Mehrspaltiger Footer

Footer-Optionen

FooterLink-Eigenschaften

FooterLinkColumn-Eigenschaften

FooterLogo-Eigenschaften

Shipyard-Branding

Layouts

Page Layout

Named Slots

Eigene Head-Elemente einfügen

Markdown Layout

Splash Layout

Soziale Vorschaubilder (OG / Twitter)

Frontmatter `image`

Seitenweiter Standard

Erzeugte Meta-Tags

Defekte Link-Erkennung

Konfiguration

Was geprüft wird

Was ignoriert wird

Internationalisierung

Auf dieser Seite