Webseiten umsetzen

Diese Seite hilft Entwicklern, öffentliche Websites mit Workspace zu planen und technisch einzuordnen. Nach der Einordnung wissen Sie, ob Sie eine normale Site, einen Produktkatalog, ein Portal oder einen vollständigen Onlineshop bauen und welche öffentlichen Verträge Sie dafür nutzen.

Grundmodell

Fast alle öffentlichen Websites folgen demselben Modell: Eine Site liefert Seiten, Vorlagen, Navigation, Assets, Domains und Releases aus. Entwickler bauen die Site-Struktur und binden nur die öffentlichen Verträge ein, die der Seitentyp wirklich braucht.

Ablauf für fast alle Websites

1. Klären Sie Zielgruppe, Seitentyp, Sprache, Domain und Verantwortlichkeit.
2. Legen Sie fest, ob die Site statische Inhalte, öffentliche Formulare, Produktdaten, Login oder Checkout braucht.
3. Planen Sie PageTypes für wiederkehrende Seitenarten wie Startseite, Detailseite, Artikel, Landingpage oder rechtliche Seite.
4. Strukturieren Sie Templates, Navigation, Übersetzungen, Styles, Scripts und öffentliche Dateien nach der Site-Projektstruktur.
5. Setzen Sie SEO-Grundlagen pro Seite: sprechender Slug, Titel, Beschreibung, Sitemap-Regel, Canonical-Verhalten und passende Sprachvariante.
6. Binden Sie dynamische Daten nur über veröffentlichte Verträge ein.
7. Prüfen Sie die Site mit Vorschau, validate, Build und fachlichem Review.
8. Veröffentlichen Sie nur den freigegebenen Release.

Die Betriebsbegriffe bedeuten hier:

Wenn Sie Site-Dateien verwalten, Dev-Mode starten, einen Mount einrichten, Build oder Veröffentlichung ausführen oder Domains binden, verwenden Sie Sites und CMS. Diese Entwicklerseite beschreibt die technische Einordnung; die Administrationsseite beschreibt den Bedien- und Betriebsablauf.

Quickstart: einfache Website bauen

Nutzen Sie diesen Quickstart, wenn Sie eine kleine öffentliche Website oder Landingpage ohne Warenkorb bauen möchten. Wenn der Seitentyp noch unklar ist, wählen Sie zuerst einen passenden Eintrag unter Website-Typen wählen.

1. Klären Sie Zweck, Zielgruppe, Sprache, Domain und Verantwortliche.
2. Legen Sie fest, ob die Site nur statische Inhalte braucht oder zusätzlich Formulare, Produktdaten, Login oder Checkout einbindet.
3. Verwenden Sie für Startseite, Detailseiten, Landingpages und rechtliche Seiten eigene PageTypes, wenn Layout oder Assets wiederkehren.
4. Erstellen Sie Pages mit stabilem Slug, Titel, Beschreibung, Navigation und passenden Container-Inhalten.
5. Legen Sie größere Inhaltsblöcke unter snippets/ ab und binden Sie sie mit type: file ein, wenn die Page-YAML sonst unübersichtlich wird.
6. Referenzieren Sie Styles und Scripts über Page oder PageType. Legen Sie öffentliche Dateien wie robots.txt, security.txt oder Downloads unter public/ ab.
7. Prüfen Sie die Site in der Vorschau und führen Sie validate aus.
8. Erzeugen Sie einen Build und veröffentlichen Sie nur den freigegebenen Release.

Der Quickstart ist abgeschlossen, wenn die Vorschau den erwarteten Stand zeigt, validate keine Blocker meldet und ein freigegebener Release veröffentlicht ist. Verwaltung, Dev-Mode, Vorschau, Build und Veröffentlichung stehen in Sites und CMS.

Angrenzende Aufgaben

Site-Projektstruktur

Lesen Sie die Struktur einer Site vor Änderungen aus:

nucli --tenant <tenant> sites structure <site-id>

Arbeiten Sie in den Quellverzeichnissen der Site. Schreiben Sie nicht direkt in dist/, releases/ oder andere generierte Build-Artefakte.

Page, PageType und Template

Eine Page-Datei beschreibt eine konkrete Seite:

type: default
variant:
  translationKey: home
  locale: de
  slug: /
title: Startseite
description: Öffentliche Startseite
navigation:
  main:
    id: home
    label: Start
    ranking: 10
containers:
  mainContent:
    - type: markdown
      content: |
        Willkommen.

type verweist auf pagetypes/<type>.yaml. Der PageType setzt gemeinsame Vorgaben, zum Beispiel Standard-Template, Styles, Scripts, Sitemap-Regel und Standard-Container. Eine Page kann Vorgaben überschreiben, wenn eine konkrete Seite fachlich abweicht. Nutzen Sie Overrides sparsam, damit wiederkehrende Seitenarten konsistent bleiben.

Templates lesen die vorbereiteten Werte der Page. Das Haupttemplate rendert Container über .Containers.<slot>, Assets über .Assets und freigegebene Seitendaten wie .Title oder .Language.

<!doctype html>
<html lang="{{ .Language }}">
  <head>
    <title>{{ .Title }}</title>
    {{ .Assets }}
  </head>
  <body>
    {{ .Containers.mainNav }}
    <main>{{ .Containers.mainContent }}</main>
  </body>
</html>

Container-Slots und Komponenten-Typen

containers ist eine Map von Slotnamen zu Komponentenlisten. Der Slotname bestimmt, wo das Haupttemplate den Inhalt einsetzt. type bestimmt, wie eine Komponente gerendert wird.

containers:
  mainContent:
    - type: markdown
      content: |
        Willkommen.
  mainNav:
    - type: navigation
      name: main
      template: navigation-main.tmpl

Der Renderer kennt diese Komponenten-Typen:

Für file erkennt Workspace html, htm, markdown, md, asciidoc und adoc. Setzen Sie format, wenn die Dateiendung das Zielformat nicht eindeutig beschreibt:

containers:
  mainContent:
    - type: file
      path: hero.txt
      format: markdown

Verwenden Sie html, markdown und asciidoc für kurze, seitenspezifische Inhalte. Verwenden Sie file, wenn mehrere Pages denselben Snippet-Inhalt einbinden oder wenn Sie Markup in snippets/ versionieren möchten.

type: file liest Dateien relativ zu snippets/. Ein Eintrag wie path: content/faq.md lädt also snippets/content/faq.md.

containers:
  mainContent:
    - type: file
      path: content/home.html
    - type: file
      path: content/faq.md

Verwenden Sie für normalen Seiteninhalt nicht type: template. Das Feld template gehört bei PageTypes, Pages und Navigations-Komponenten zum Template-Vertrag, nicht zu einem frei wählbaren Content-Include. Verwenden Sie auch keine YAML-Syntax wie !include; der Site-Loader wertet sie nicht als Include aus.

type: file bindet statische Inhaltsdateien ein. Go-Template-Ausdrücke in type: html, type: markdown und type: asciidoc werden ausgewertet; bei type: file bleibt die Datei bewusst statischer Seiteninhalt. Wenn Sie Produktkarten, Preise oder Varianten darstellen, verwenden Sie die dokumentierten Storefront- und Snippet-Verträge.

Navigation rendern

Navigation entsteht aus den navigation-Einträgen der Pages und aus Navigations-Komponenten in PageTypes oder Pages. Arbeiten Sie mit stabilen technischen IDs:

• Verwenden Sie id als dauerhaften Navigationsanker.
• Lokalisieren Sie label pro Sprache.
• Steuern Sie die Reihenfolge über ranking.
• Verweisen Sie bei Unterpunkten mit parent auf die ID des Elternpunkts.
• Schreiben Sie keine eigenen children-Arrays. Workspace baut Kinder aus den Parent-Bezügen.

Ein PageType kann Navigations-Slots definieren:

template: main.tmpl
containers:
  mainNav:
    - type: navigation
      name: main
      template: navigation-main.tmpl
  legalNav:
    - type: navigation
      name: legal
      template: navigation-legal.tmpl

name wählt das Menü, zum Beispiel navigation.main aus den Page-Dateien. template zeigt auf eine Datei unter templates/. Das Navigationstemplate bekommt .Name, .Links und .Component; Einträge in .Links können .Children enthalten.

<nav aria-label="{{ .Name }}">
  {{ range .Links }}
    <a href="{{ .URL }}">{{ .Label }}</a>
    {{ range .Children }}
      <a href="{{ .URL }}">{{ .Label }}</a>
    {{ end }}
  {{ end }}
</nav>

Dynamische Produktdetailseiten

Nutzen Sie eine dynamische Produktdetailseite, wenn viele Produkte dasselbe Detail-Layout verwenden sollen. Legen Sie keine Page-Datei pro Produkt an. Eine einzige Site-Page definiert Layout, Sprache, Navigation und Produktbereiche; das konkrete Produkt kommt zur Laufzeit aus der ProductRoute des aktuellen Sales Channels.

Die dynamische Produktdetailseite verbindet drei Verträge:

Produkt-Snippets sind nicht dasselbe wie Dateien im Site-Verzeichnis snippets/. Dateien unter snippets/ sind statische, wiederverwendbare Site-Teile für type: file. Ein productSnippet verweist dagegen auf ein generiertes Varianten-Artefakt aus PIM. Wie Sie solche Produkt-Snippets planen, bauen, per Preview prüfen und per Snippet-Rebuild ausliefern, steht in Snippet-Vorlagen entwickeln.

Die dynamische Page setzt dynamicRoute.kind: productDetail und einen öffentlichen Prefix. Der Prefix bildet zusammen mit ProductRoute.slug die sichtbare URL.

type: product-detail
variant:
  translationKey: product-detail
  locale: de-DE
  slug: _dynamic/product-detail
dynamicRoute:
  kind: productDetail
  prefix: de/produkte
containers:
  mainContent:
    - type: productSnippet
      name: product-detail-hero
      params:
        required: true
    - type: productSnippet
      name: product-detail-specs

Bei einem Aufruf wie /de/produkte/<product-route-slug> löst Workspace zuerst Host, Site, Sales Channel und Sprache auf. Danach sucht Workspace die passende ProductRoute, rendert die dynamische Page und ersetzt jeden productSnippet-Marker durch das passende Snippet-Artefakt für Tenant, Variante, Locale und Sales Channel.

params.required: true macht ein Produkt-Snippet verpflichtend. Nutzen Sie required nur für Bereiche, ohne die die Detailseite fachlich nicht ausgeliefert werden soll. Wenn ein verpflichtendes Produkt-Snippet fehlt, liefert die Live-Seite 503 Service Unavailable mit Retry-After, statt einen unvollständigen Produktbereich still auszuliefern. Optionale Snippets bleiben leer, wenn kein passendes Artefakt existiert.

Veröffentlichen Sie nach Template-Änderungen einen neuen Site Release. Nach Inhalts-, Medien- oder Snippet-Vorlagenänderungen muss der Snippet-Rebuild die benötigten Variant-Artefakte erzeugen.

Wenn die Produktdetailseite zusätzlich Anfrage, Newsletter-Anmeldung, Website Chat oder Kampagnenmessung braucht, nutzen Sie die fertigen Website-Integrationen im nächsten Abschnitt.

Fertige Website-Integrationen einbinden

Produktdetailseiten, Landingpages und Corporate-Sites brauchen oft mehr als Produktdarstellung: Anfrageformular, Newsletter-Anmeldung, Website Chat oder Kampagnenmessung. Bauen Sie diese Funktionen nicht als Sitegenerator-Plugin nach. Workspace stellt dafür fertige öffentliche Verträge bereit.

Für Contact Forms und Website Chat nutzen Sie die technische Anleitung Storefront-Erweiterungen. Die Seite gilt auch für normale Websites, wenn diese nur Formular oder Chat einbinden und keinen vollständigen Onlineshop bauen.

Newsletter-Anmeldungen senden Sie an den öffentlichen Subscribe-Endpunkt:

POST /api/v1/public/v1/newsletter/subscribe

Die Payload enthält tenantId, newsletterListId, email und optional locale. Behandeln Sie die Annahme neutral und bauen Sie keinen lokalen Listen-Fallback. Workspace versendet die Bestätigung und trägt Empfänger erst nach erfolgreichem Double-Opt-in als subscribed ein.

Kampagnen- und Newsletter-Auswertung richten Betreiber über Website-Analytics und Marketing-Attribution ein. Newsletter-Links werden beim finalen Newsletter-Versand umgeschrieben; manuelle Tracking-Links gehören in Marketing-Kampagnen, nicht hart in Templates. Website-Seiten dürfen Tracking nur mit fachlich freigegebenen Datenschutz- und Consent-Grundlagen verwenden.

Sitegenerator-Plugins einbinden

Eine Plugin-Komponente ist nur eine Einbindestelle im Site-YAML. Sie erzeugt kein Plugin und lädt keinen Code aus dem Site-Projekt. Das eigentliche Plugin muss vorher serverseitig im Sitegenerator registriert sein. Page-Autoren können keinen neuen Go-Plugin-Code allein durch YAML erzeugen.

In einer Standard-Site kann es deshalb null nutzbare Sitegenerator-Plugins geben. Das ist kein Fehler: type: plugin ist eine Erweiterungsstelle für bereitgestellte serverseitige Bausteine, kein Plugin-Marktplatz und kein Mechanismus, mit dem Site-Dateien eigene Backend-Logik installieren. Verwenden Sie type: plugin nur, wenn Ihre Workspace-Instanz einen konkreten Plugin-Namen und dessen params-Vertrag dokumentiert.

containers:
  mainContent:
    - type: plugin
      name: contactTeaser
      params:
        headline: Beratung anfragen
        target: /kontakt

Dieses Beispiel ist nur das YAML-Muster. contactTeaser funktioniert erst, wenn genau dieser Name serverseitig registriert wurde. Wenn kein Plugin unter diesem Namen existiert, ist der Eintrag ungültig.

Der Renderer sucht ein registriertes Plugin mit diesem name und übergibt params als strukturierte Werte. Das Plugin gibt HTML zurück oder meldet einen Fehler. Wenn kein Plugin unter diesem Namen registriert ist, rendert Workspace einen Fehlerhinweis im Container.

Prüfen Sie vor dem Einsatz eines Plugins:

• Welcher Plugin-Name ist für diese Workspace-Instanz freigegeben?
• Welche params sind Pflicht, optional und stabil?
• Welche Daten darf das Plugin lesen und welche öffentlichen Verträge nutzt es?
• Wie verhält sich das Plugin bei fehlenden Daten oder Build-Fehlern?
• Gibt es eine einfachere Umsetzung mit markdown, html, asciidoc, file, navigation oder productSnippet?

Nutzen Sie Plugins nur für bewusst bereitgestellte serverseitige Bausteine. Für normale Inhaltsblöcke sind markdown, html, asciidoc oder file leichter prüfbar. Für Storefront-Funktionen bleiben veröffentlichte Public- und Storefront-Verträge die Integrationsgrenze; bauen Sie keine internen API- Fallbacks in ein Plugin.

Internationalisierung und Assets

Mehrsprachige Seiten verwenden Varianten. variant.translationKey verbindet Sprachvarianten fachlich, variant.locale setzt die Sprache und variant.slug setzt den öffentlichen Pfad der konkreten Variante.

Pflegen Sie Übersetzungen an den passenden Stellen:

• Page-Felder wie title, description, Navigationslabels und sichtbare Inhalte pro Sprachvariante.
• Übersetzungsbündel unter i18n/ für wiederverwendbare Texte.
• translationScopes, wenn eine Page bestimmte Übersetzungsbereiche braucht.
• optionale lokale translations, wenn eine Page eigene kleine Textbausteine liefert.

Templates können übersetzte Werte über die freigegebenen i18n-Funktionen lesen. Halten Sie technische IDs, Navigations-IDs und Translation Keys stabil. Übersetzen Sie sichtbare Labels, nicht die Identität des Eintrags.

Referenzieren Sie Styles und Scripts über PageTypes oder Pages. Der Build bündelt referenzierte Assets und stellt sie dem Template über .Assets bereit.

Dateien unter public/ werden unverändert veröffentlicht. Nutzen Sie public/ für statische Dateien wie robots.txt, security.txt, Web-Manifeste, SVGs, PDFs oder JSON-Dateien. Verwenden Sie dort keine Template-Platzhalter, keine Secrets und keine unfertigen Entwürfe.

SEO und Auffindbarkeit planen

SEO entsteht nicht erst am Ende. Planen Sie Suchmaschinen, interne Suche und teilbare Links zusammen mit der Seitenstruktur.

Website-Typen wählen

Was immer gleich bleibt

• Der Server entscheidet über Tenant, Site, Domain, Veröffentlichung und bei Storefronts über Sales Channel, Preise, Verfügbarkeit, Checkout und Zahlarten.
• Der Client liest veröffentlichte Verträge und rendert deren Ergebnis. Er baut keinen lokalen Ersatz für fehlende Daten, fehlende Domainbindung oder blockierte Readiness.
• Öffentliche Seiten zeigen keine Admin-Navigation, keine internen IDs ohne fachlichen Zweck, keine Secrets und keine unfertigen Entwürfe.
• Templates, PageTypes und Snippets reduzieren Wiederholung. Sie ersetzen keine fachliche Freigabe für Inhalte, Datenschutz, Tracking oder rechtliche Texte.
• Fehler- und Diagnoseausgaben bleiben public-safe. Geben Sie keine Tokens, Sessions, Rohdaten, vollständigen Payloads oder internen Pfade an Besucher weiter.

Onlineshop als eigene Lösung

Ein Onlineshop ist mehr als eine Website mit Produktseiten. Er braucht einen serverseitig aufgelösten Storefront-Kontext, veröffentlichte Produkte, Preise, Verfügbarkeit, Warenkorb, Versand, Checkout, Payment, Account-Flows, Firmenzugang und Angebotsanfragen. Starten Sie deshalb mit Onlineshop, wenn Besucher kaufen, Preise im Kontext sehen oder einen Warenkorb führen sollen.

Nutzen Sie die Onlineshop-Detailseiten für die technische Umsetzung:

• Katalog, Preise und Produktdarstellung
• Warenkorb, Checkout und Payment
• Login, Gastkauf und B2B
• Storefront-Erweiterungen

Verwenden Sie keine internen PIM-, Commerce-, Inventory-, Admin- oder CRUD-Endpunkte als Storefront-Fallback. Wenn ein öffentliches Ergebnis leer oder blockiert ist, klären Sie Site, Veröffentlichung, Sales Channel, Readiness, Preise oder Berechtigungen.

Nächste Schritte

• Allgemeine Site-Verwaltung, Domain, Dev-Mode, Build und Publish: Sites und CMS
• API- und CLI-Integration für eigene Clients: Integration
• Backend-Verträge für eigene Oberflächen: Backend-Integration für eigene Clients
• Onlineshop als Commerce-Storefront: B2B-Onlineshop bauen