Redaktion

Wie du News-Beiträge schreibst und die Roadmap pflegst. Beides sind Dateien im Repository guppy-docs, es gibt kein Backend und kein Login.

Wenn du wissen willst, was nach dem Merge automatisch passiert, steht das unter Automatisierung.

Sprachen

Die Produktseiten sind bewusst nicht gespiegelt:

Seite	Sprache	Warum
Changelog	Englisch	Die Einträge stehen auf Englisch in den Repositories
News	Deutsch	Interne Zielgruppe
Roadmap	Deutsch	Interne Zielgruppe

Das ist die einzige Ausnahme von der Regel, dass jede Seite auf Deutsch und Englisch existiert. Alle anderen Seiten, auch diese hier, brauchen eine englische Entsprechung unter docs/en/.

News-Beitrag schreiben

Ein Beitrag ist eine Markdown-Datei in docs/news/. Mehr passiert nicht: der Content-Loader findet sie beim Build automatisch, du musst nichts registrieren.

Dateiname

docs/news/JJJJ-MM-TT-kurzer-slug.md

Beispiel: docs/news/2026-08-27-releases-melden-sich-selbst.md

Der Slug landet in der URL. Nimm keine Umlaute und kein ß darin, sonst wird die Adresse unschön kodiert. Im Text selbst schreibst du natürlich normal.

Frontmatter

---
title: 'Releases melden sich jetzt von selbst'
date: '2026-08-27'
author: digital.manufaktur
tags: [ankündigung, automatisierung]
excerpt: 'Ein bis zwei Sätze, die den Beitrag zusammenfassen.'
sidebar: false
aside: true
editLink: false
---

Feld	Pflicht	Wirkung
title	ja	Überschrift in der Übersicht und in der Slack-Meldung
date	ja	Sortierung, Anzeige, ISO-Format JJJJ-MM-TT
author	nein	Standard ist digital.manufaktur
tags	nein	Werden in Slack zu Hashtags, siehe unten
excerpt	ja	Anrisstext in der Übersicht und in der Slack-Meldung
sidebar	ja	false, Beiträge haben keine Seitenleiste
aside	ja	true, blendet das Inhaltsverzeichnis ein
editLink	ja	false

Setz title, date und excerpt immer in Anführungszeichen. Ein Doppelpunkt gefolgt von einem Leerzeichen bricht sonst den YAML-Parser und damit den Build.

Optional gibt es noch plugin und version, wenn du einen Beitrag mit einem konkreten Release verknüpfen willst.

Aus Tags werden Hashtags

tags: [ankündigung, automatisierung] wird in Slack zu #Ankündigung #Automatisierung. Der erste Buchstabe wird großgeschrieben, Bindestriche und Leerzeichen fallen weg.

Insgesamt zeigt eine Meldung höchstens acht Hashtags. #GuppyNews steht immer vorn, dann kommen Typ und Produkt, deine Tags stehen hinten. Bei vielen Tags fallen deine also zuerst raus. Zwei bis drei sind eine gute Zahl.

Aufbau des Beitrags

# Releases melden sich jetzt von selbst

<NewsMeta />

Erster Absatz. Der trägt den Beitrag, denn viele lesen nicht weiter.

## Zwischenüberschrift

<NewsMeta /> gehört direkt unter die H1. Die Komponente rendert Datum, Autor und Tags. Ohne sie fehlt die Zeile.

Ton

Duzen, nie siezen. Imperativ, wo es passt: Öffne, Wähle, Nutze. Umlaute und ß richtig schreiben, also Änderung statt Aenderung und heißt statt heisst.

Der lange Gedankenstrich (Geviertstrich, Unicode U+2014) ist im gesamten Repository verboten. Nimm stattdessen einen Doppelpunkt nach einem Stichwort, ein Komma im laufenden Satz, oder einen Halbgeviertstrich für Bereiche.

Roadmap pflegen

Die Roadmap ist kein Markdown, sondern eine typisierte Datei:

docs/.vitepress/data/roadmap.ts

Ein Eintrag sieht so aus:

{
  id: 'changelog-convention-rollout',
  title: 'Ein einheitliches Changelog-Format in allen Repositories',
  summary:
    'Das dokumentierte Format überall übernehmen und jedes Release taggen.',
  status: 'next',
  products: ['DmfGuppyTheme', 'VatToggle'],
}

Feld	Wirkung
id	Eindeutig, wird für den Anker in der URL genutzt
title	Eine Zeile, keine Beschreibung
summary	Ein bis zwei Sätze: was und warum
status	current, next oder future
products	Namen aus dem Changelog, exakt geschrieben

Die drei Stufen erscheinen auf der Seite als Aktuelle Projekte, Als Nächstes und Weiter gedacht.

products muss zu den Produktnamen im Changelog passen, also DmfGuppyTheme und nicht Guppy Theme. Die gültigen Namen stehen in docs/.vitepress/data/changelog.json.

Einen erledigten Eintrag löschst du. Die Roadmap ist kein Archiv, dafür gibt es den Changelog.

Vorschau

npm run docs:dev

Läuft auf http://localhost:5173 und lädt bei jeder Änderung neu. News liegen unter /news/, die Roadmap unter /roadmap.

Vor dem Commit einmal:

npm run docs:build

Der Build prüft jeden internen Link. Ein Tippfehler in einem Link lässt den Build scheitern, und das ist Absicht.

Danach

Committen, Merge Request auf main, fertig. Nach dem Merge deployt die Pipeline die Seite und meldet den Beitrag in #guppy. Du musst nichts anstoßen.

Details dazu unter Automatisierung.