Kiekkist
Menü
EN

Anleitung · Astro

Astro-Theme installieren

Aus dem Designpaket wird ein Astro-Projekt. Jeder Abschnitt ist eine Komponente, die Texte liegen als JSON daneben. npm run build macht daraus eine statische Website.

Im Beispiel heißt das Design Fieldnote (kostenlos, Kurzname fieldnote). Bei deinem Design steht dort sein Kurzname.

Was du brauchst

Was im Export liegt

Ordner fieldnote-astro/

package.json
Astro 7 und @astrojs/sitemap, Skripte dev, build, preview.
astro.config.mjs
Domain (site), Schrägstrich am Ende jeder Adresse, Sitemap.
src/pages/
Eine .astro-Datei pro Seite.
src/components/
Eine Komponente pro Abschnitt. Kopfbereiche gibt es pro Seite, wegen des markierten Menüpunkts.
src/content/
Texte: sections/<abschnitt>.json pro Abschnitt, Listen als <liste>.json.
src/layouts/Base.astro
Grundgerüst mit Titel, Beschreibung, Canonical und Open Graph.
public/
tokens.css, assets/ mit CSS, Schriften, Bildern, dazu .htaccess und _headers mit Sicherheits-Headern.
AGENTS.md
Regeln für KI-Assistenten: nur Tokens, keine fremden Server, Rechtsseiten verlinkt lassen.
DESIGN.md, EXPORT.md
Gestaltungsregeln und Export-Bericht.

Von Hand

  1. Fertigen Export herunterladen

    Kostenlose Designs lädst du auf der Designseite, gekaufte auf der Download-Seite mit deinem Lizenzschlüssel. Danach wählst du, was du laden willst: Astro-Projekt, alles in einem ZIP oder nur das Designpaket. Entpackt liegt der Export in fieldnote/exports/astro/, mit INSTALL.md und EXPORT.md. Das ist derselbe Inhalt wie fieldnote-astro/ in den Schritten unten.

  2. Oder selbst erzeugen

    Wer den Export aus einem geänderten Designpaket neu bauen will, nimmt das Kiekkist-Werkzeug kk. Es ist Open Source, läuft lokal und braucht Node.js 22 oder neuer. Lege es neben den Designordner (im Download „Nur Designpaket“ heißt er fieldnote/). Der Befehl schreibt fieldnote-astro/; --no-check lässt die Bildvergleichs-Prüfung weg (dafür einmal npx playwright install chromium).

    git clone https://github.com/tillheidrich/kiekkist
cd kiekkist && npm ci && cd ..
node kiekkist/cli/kk.js export ./fieldnote --target astro --site-url https://www.deine-domain.de --no-check

  3. Installieren und starten

    --site-url trägt deine Domain in astro.config.mjs ein, für Sitemap und Canonical. Ohne die Option steht dort ein Platzhalter, den du später änderst.

    cd fieldnote-astro
npm install
npm run dev

  4. Im Browser ansehen

    Die Seite läuft unter http://localhost:4321/. Änderungen an Dateien siehst du sofort.

  5. Bauen

    Der Befehl schreibt die fertige Website nach dist/: HTML, CSS, Schriften, Bilder, sitemap-index.xml. Mit npm run preview siehst du den gebauten Stand vorher an.

    npm run build

  6. Veröffentlichen

    Lade den Inhalt von dist/ in das Hauptverzeichnis deines Webspace, per SFTP oder FTP. Versteckte Dateien mitnehmen: .htaccess setzt bei Apache-Hostern HTTPS-Weiterleitung und Sicherheits-Header. Bei Hostern mit Git-Anbindung trägst du npm run build als Build-Befehl und dist als Ausgabeordner ein. Ein Server mit Node ist nicht nötig.

Mit KI-Assistent

Dein KI-Coding-Assistent kann den Export erzeugen, die Beispielinhalte ersetzen und dir sagen, was du noch selbst tun musst. Gib ihm den entpackten Designordner und diese Dateien zu lesen:

  • fieldnote/DESIGN.md: Gestaltungsregeln, Farben, Schriften, was man nicht ändern sollte
  • fieldnote/tokens.json und tokens.css: alle Farb-, Schrift- und Abstandswerte
  • fieldnote/README.md: Inhalt des Pakets und was vor dem Start ersetzt werden muss
  • fieldnote/LICENSE.md: was du mit Code, Texten und Fotos darfst
  • fieldnote/UEBERGABE/: Vorlagen für die Übergabe an deinen Kunden (Deutsch und Englisch)
  • im Export fieldnote-astro/AGENTS.md und EXPORT.md

Prompt zum Kopieren. Ersetze die Angaben in eckigen Klammern. Statt fieldnote setzt du den Kurznamen deines Designs ein.

Im Ordner ./fieldnote liegt ein Website-Design als Paket. Bau daraus eine Astro-Website für [Firmenname], Domain [www.domain.de]. 1. Lies zuerst fieldnote/DESIGN.md, README.md und LICENSE.md. Gestaltung nicht ändern, nur Werte aus den Tokens verwenden. 2. Hol das Kiekkist-Werkzeug (git clone https://github.com/tillheidrich/kiekkist, darin npm ci) und erzeuge den Export: node kiekkist/cli/kk.js export ./fieldnote --target astro --site-url https://[www.domain.de] --no-check. Lies danach fieldnote-astro/AGENTS.md und EXPORT.md und halte dich an die Regeln dort. 3. Ersetze alle Beispielinhalte in src/content durch meine Angaben: [Name, Adresse, Leistungen, Texte]. Texte nur in src/content ändern, nicht in den Komponenten. 4. Fülle die Platzhalter auf den Rechtsseiten mit meinen Daten, frag mich nach allem, was du nicht weißt. 5. npm install, npm run build. Behebe Fehler, bis der Build ohne Fehler durchläuft, und zeig mir, was du geändert hast.

Lass dir jede Änderung zeigen, bevor sie auf die Live-Website geht. Zugangsdaten und Lizenzschlüssel gehören nicht in den Chat und nicht ins Repository.

Inhalte, Bilder und Logo ersetzen

Texte: in src/content/sections/<abschnitt>.json. Listen wie Projekte, Team oder Preise stehen in eigenen Dateien in src/content/. Seitentitel und Beschreibung stehen oben in der jeweiligen Datei in src/pages/.

Bilder: in public/assets/img/. Die Pfade stehen in den JSON-Dateien (imgSrc, imgSrcset) oder direkt in der Seite. Entweder neues Bild unter gleichem Namen und in denselben Größen speichern, oder die Pfade in der JSON-Datei ändern. Alternativtext (imgAlt) mit anpassen.

Logo: SVG im Kopfbereich. Es steht in src/components/SiteHeader.astro und in den Kopfbereichen der einzelnen Seiten (*SiteHeader.astro). Alle ändern.

Farben und Schriften anpassen

Alle Farben, Schriften und Abstände stehen als CSS-Variablen in public/tokens.css, zum Beispiel --c-paper oder --font-sans. Wert ändern, fertig: Das restliche CSS liest nur diese Variablen.

Für größere Änderungen: Werte in tokens.json im Designpaket ändern und neu exportieren. Achtung, das überschreibt den Exportordner nur mit --force; sichere vorher deine Inhalte aus src/content/.

Andere Schrift: woff2 nach public/assets/fonts/, @font-face in fonts.css ergänzen, --font-… in tokens.css umstellen. Keine Schriften von fremden Servern laden.

Farben sind in OKLCH angegeben. Prüf nach jeder Änderung den Kontrast von Text zu Hintergrund (mindestens 4,5:1).

Was die Lizenz erlaubt

Gekauftes Design: Du darfst damit beliebig viele Websites bauen, eigene und für Kunden, und sie mit allen Rechten übergeben. Dein Kunde darf die Seite ohne dich weiterbetreiben. Nicht erlaubt ist, das Design selbst weiterzugeben oder zu verkaufen, auch nicht als Vorlage, Theme oder Kit. Der volle Text steht in der Lizenz.

Kostenloses Design: Es gilt LICENSE.md im Paket. Bei Fieldnote ist das CC BY 4.0: Nutzung auch für Kunden und kommerziell, mit einer kurzen Namensnennung im Quelltext oder auf einer Credits-Seite.

Fotos aus dem Paket darfst du nur als Teil der Website verwenden, die du damit baust. Nicht einzeln weitergeben, nicht als Stockfotos.

Schriften stehen unter der SIL Open Font License. Die Lizenzdateien LICENSE-*.txt bleiben neben den Schriftdateien liegen.

Deinen Lizenzschlüssel legst du nie ins Repository oder in Theme-Dateien. KIEKKIST-LICENCE.txt im Paket nennt nur Lizenz-ID und Projekt.

Häufige Probleme

npm install oder npm run build bricht mit einem Hinweis auf die Node-Version ab.

Astro 7 braucht Node.js 22.12 oder neuer. node -v zeigt deine Version. Aktualisieren, dann node_modules löschen und npm install neu ausführen.

Sitemap und Canonical zeigen auf example.invalid.

Die Domain fehlt. Trag sie in astro.config.mjs bei site ein, oder exportiere mit --site-url. Dann neu bauen.

Auf dem Server fehlen CSS, Bilder oder Schriften.

Die Pfade beginnen mit /assets/ und gehen von der Domain-Wurzel aus. Liegt die Seite in einem Unterordner, stimmen sie nicht. Lade dist/ in das Hauptverzeichnis oder nutze eine eigene Subdomain.

Ein eingebettetes Video, Kartendienst oder Formular-Dienst wird blockiert.

public/_headers und public/.htaccess setzen eine strenge Content-Security-Policy: nur Inhalte von der eigenen Domain. Trag den Dienst dort gezielt ein (frame-src, form-action, script-src) und ergänze die Datenschutzerklärung.

Das Formular schickt nichts ab.

Das ist Absicht: Im Paket ist es eine Demo ohne Empfänger. Trag die Adresse deines Formular-Empfängers als action ein und stell auf method="post" um.

Der Export bricht mit „export refused“ ab.

kk prüft das Design vor dem Export und nennt jeden Fehler mit Datei und Zeile, zum Beispiel einen Abschnitt ohne Namen. Das passiert, wenn du die HTML-Seiten im Paket vorher umgebaut hast. Behebe die genannte Stelle oder exportiere aus dem unveränderten Paket und ändere danach. Prüfe auch die Node-Version mit node -v: Unter 22 läuft das Werkzeug nicht.

Was wir geprüft haben

Geprüft mit zwei Designs (Fieldnote und Kestrel Row): Export erzeugt, npm install und npm run build mit Astro 7.4 und Node 22 ohne Fehler, alle Seiten gebaut.

Mehr zum Export Alle Anleitungen Zur Galerie

Andere Exporte: WordPress, HTML, React, Elementor