Editorial

How to write news posts and maintain the roadmap. Both are files in the guppy-docs repository. There is no backend and no login.

For what happens automatically after a merge, see Automation.

Languages

The product pages are deliberately not mirrored:

Page	Language	Why
Changelog	English	The entries are written in English in the repositories
News	German	Internal audience
Roadmap	German	Internal audience

That is the only exception to the rule that every page exists in German and English. Every other page, including this one, needs a counterpart under docs/en/.

Writing a news post

A post is a Markdown file in docs/news/. That is all: the content loader picks it up at build time, you register nothing.

Filename

docs/news/YYYY-MM-DD-short-slug.md

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

The slug becomes the URL. Keep umlauts and ß out of it, or the address gets awkwardly encoded. The text itself is unaffected.

Frontmatter

---
title: 'Releases melden sich jetzt von selbst'
date: '2026-08-27'
author: digital.manufaktur
tags: [ankündigung, automatisierung]
excerpt: 'One or two sentences summarising the post.'
sidebar: false
aside: true
editLink: false
---

Field	Required	Effect
title	yes	Heading in the index and in the Slack message
date	yes	Sorting and display, ISO format YYYY-MM-DD
author	no	Defaults to digital.manufaktur
tags	no	Become hashtags in Slack, see below
excerpt	yes	Teaser in the index and in the Slack message
sidebar	yes	false, posts have no sidebar
aside	yes	true, shows the table of contents
editLink	yes	false

Always quote title, date and excerpt. A colon followed by a space otherwise breaks the YAML parser and with it the build.

There are two optional fields, plugin and version, for tying a post to a specific release.

Tags become hashtags

tags: [ankündigung, automatisierung] becomes #Ankündigung #Automatisierung in Slack. The first letter is capitalised, hyphens and spaces are dropped.

A message shows at most eight hashtags. #GuppyNews always leads, then type and product, and your tags come last. With many tags yours are dropped first, so two or three is a good number.

Structure

# Releases melden sich jetzt von selbst

<NewsMeta />

First paragraph. It carries the post, because many readers stop there.

## Subheading

<NewsMeta /> belongs directly under the H1. It renders date, author and tags. Without it that line is missing.

Tone

Second person, direct, imperative where it fits. In German posts use du, never Sie, and write umlauts and ß properly: Änderung not Aenderung, heißt not heisst.

The em dash (U+2014) is banned across the whole repository. Use a colon after a label, a comma mid-sentence, or an en dash for ranges.

Maintaining the roadmap

The roadmap is not Markdown but a typed module:

docs/.vitepress/data/roadmap.ts

One entry looks like this:

{
  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'],
}

Field	Effect
id	Unique, used as the anchor in the URL
title	One line, not a description
summary	One or two sentences: what and why
status	current, next or future
products	Names from the changelog, spelled exactly

The three stages render as Aktuelle Projekte, Als Nächstes and Weiter gedacht. The content is German, since the roadmap is a German page.

products must match the product names in the changelog, so DmfGuppyTheme and not Guppy Theme. The valid names are in docs/.vitepress/data/changelog.json.

Delete an entry once it is done. The roadmap is not an archive; the changelog is.

Preview

npm run docs:dev

Serves http://localhost:5173 with hot reload. News lives at /news/, the roadmap at /roadmap.

Before committing, once:

npm run docs:build

The build checks every internal link. A typo in a link fails the build, and that is deliberate.

Afterwards

Commit, merge request against main, done. After the merge the pipeline deploys the site and announces the post in #guppy. You trigger nothing.

Details under Automation.