Astro-Entwickler in Bonn

#Lange Texte in Astro: was Redakteure schreiben und was daraus wird

Ich bin Mariusz Szatkowski, arbeite seit 2006 mit WordPress und baue Websites heute auch mit Astro. Ich sitze in Gdynia, arbeite vollständig remote und schriftlich, ohne Meetings und Telefonate. Diese Seite richtet sich an Organisationen in Bonn, deren Website vor allem aus langen Texten besteht, und an die Menschen, die diese Texte schreiben.

Mein Thema ist die Arbeit mit Inhalten: Markdown und MDX in Astro, Frontmatter, Komponenten im Fließtext, Plugins für Überschriften, Tabellen und Fußnoten, Codeblöcke mit Shiki und Markdoc als Alternative. Was ich zu Astro schreibe, stammt aus der Dokumentation unter docs.astro.build und aus mdxjs.com. Versionsangaben stammen aus der npm-Registry (Stand 11. November 2026): Astro 7.4.11, @astrojs/mdx 8.1.5, @astrojs/markdoc 2.1.4.

Ein Beispiel aus Bonn zeigt, wie viel Struktur ein langer Fachtext braucht. Das Bundeskartellamt hat nach eigener Beschreibung seinen Sitz in Bonn. In seiner Entscheidungsdatenbank standen bei meinem Abruf am 11. November 2026 2802 Einträge. Jeder hat ein Geschäftszeichen, eine Entscheidungsart, ein Datum, und die Liste lässt sich nach Arbeitsbereich und Erscheinungsjahr filtern. Die Einträge öffnen als HTML-Seiten. Ich weiß nicht, womit die Behörde ihre Seiten baut, und es geht hier nicht um sie. Der Aufbau zeigt nur, was ein langer Text als Daten braucht: Metadaten für die Filter, eine klare Gliederung und ein Text, der sich weiter bearbeiten lässt. Genau dafür ist Frontmatter da.

Foto: Matthias Zepper, CC BY-SA 2.5, Wikimedia Commons.

#Frontmatter: die Daten vor dem Text

Eine Markdown-Datei in Astro kann am Anfang Frontmatter in YAML oder TOML tragen, etwa title, author oder description. Importieren Sie die Datei, stehen die Felder im Export frontmatter. In einer Content Collection stehen sie unter data. Die Dokumentation empfiehlt Collections für zusammengehörige Inhalte mit gleicher Struktur, weil sie Validierung, Typsicherheit und Editor-Hilfen mitbringen. Wie Collections aufgebaut werden, beschreibe ich auf der Seite für Stuttgart, und wie Inhalte aus einem Redaktionssystem oder einer Datenquelle in eine Collection kommen, auf der Seite für Nürnberg.

Für einen langen Fachtext schlage ich meist diese Felder vor, jedes mit einem Zweck:

• Titel und Kurzfassung, für Überschrift, Suchergebnis und Vorschau.
• Datum und Stand, damit Leser sehen, wie aktuell der Text ist.
• Aktenzeichen oder Kennung, wenn Ihre Texte eine haben.
• Schlagwörter, für Filter und verwandte Beiträge.

Plugins können Felder auch berechnen. Laut Dokumentation lassen sich Werte in data.astro.frontmatter schreiben, und sie stehen danach im Layout und beim Rendern einer Collection zur Verfügung. Die Dokumentation verweist dafür auf ein Rezept zur Lesezeit.

#Markdown in Astro 7: Prozessor, Tabellen, Fußnoten

Astro rendert Markdown mit einem Prozessor, den die Option markdown.processor wählt (seit Astro 6.4.0). Seit Astro 7 ist laut Dokumentation Sätteri der Standard, ein in Rust geschriebener Compiler aus @astrojs/markdown-satteri (npm-Version 0.4.9, Stand 11. November 2026). Wer die Welt der remark- und rehype-Plugins braucht, wählt unified() aus @astrojs/markdown-remark.

GitHub-Flavored Markdown ist standardmäßig eingeschaltet. Es bringt Tabellen, Durchstreichen, Aufgabenlisten und Fußnoten. Für einen Text mit Quellenangaben sind Fußnoten und Tabellen das Wichtigste. Die Beschriftungen der Fußnoten sind einstellbar, bei Sätteri mit features.gfm.footnotes und den Schlüsseln label, backLabel und backContent:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';

export default defineConfig({
  markdown: {
    processor: satteri({
      features: {
        gfm: { footnotes: { label: 'Fußnoten', backLabel: 'Zurück zum Text' } },
      },
    }),
  },
});

Bei unified() heißt dieselbe Einstellung remarkRehype mit footnoteLabel und footnoteBackLabel. Ich prüfe die Schreibweise beim Einrichten im Projekt, die Dokumentation zeigt sie nur als Auszug.

Zwei Voreinstellungen erwähne ich Kunden vorab. Erstens ist die Smart-Punctuation-Funktion standardmäßig an: Sie wandelt nach der Dokumentation Anführungszeichen, doppelte Bindestriche und drei Punkte um. Bei deutschen Texten prüfe ich an Ihrem Material, ob die Anführungszeichen so herauskommen, wie Ihr Haus sie schreibt. Zweitens setzt Astro Überschrift-IDs mit github-slugger, sodass Sprungmarken wie #fussnoten entstehen. Setzt ein Plugin eigene IDs, bleiben sie erhalten, weil Astro seine IDs nach den eigenen Plugins vergibt.

#Plugins für Gliederung und Struktur

Die Dokumentation unterscheidet mdast-Plugins (remark, arbeiten am Markdown-Baum) und hast-Plugins (rehype, arbeiten am HTML-Baum). Bei Sätteri heißen die Optionen mdastPlugins und hastPlugins, bei unified() remarkPlugins und rehypePlugins. Die ältere Schreibweise markdown.remarkPlugins auf oberster Ebene ist in der Konfigurationsreferenz als veraltet markiert, Plugins gehören an den Prozessor:

import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';

export default defineConfig({
  markdown: { processor: unified({ remarkPlugins: [remarkToc] }) },
});

Das Beispiel ist das aus der Konfigurationsreferenz: remark-toc erzeugt ein Inhaltsverzeichnis. Ob ich es oder eigenen Code auf Basis von getHeadings() nehme, entscheide ich am Text. Ein Plugin, das Überschriften-IDs braucht, setze ich laut Dokumentation hinter rehypeHeadingIds (Unified) oder satteriHeadingIdsPlugin() (Sätteri).

#MDX: Komponenten mitten im Text

Mit der Integration @astrojs/mdx können Sie in .mdx-Dateien Variablen, Ausdrücke und Komponenten verwenden. Installation: npx astro add mdx. Das ist die Antwort auf die Frage, wie ein Hinweiskasten, eine Rechenhilfe oder eine Grafik in einen Text kommt, ohne dass der Redakteur HTML schreibt.

import Hinweis from '../components/Hinweis.astro';

# {frontmatter.title}

Der Absatz bleibt ein Absatz.

<Hinweis typ="frist">Die Stellungnahme ist schriftlich einzureichen.</Hinweis>

Nach der Dokumentation lassen sich in MDX außerdem HTML-Elemente auf eigene Komponenten abbilden: Ein exportiertes Objekt components ordnet etwa blockquote einer Astro-Komponente zu. So bekommen alle Zitate dasselbe Aussehen, ohne dass der Redakteur etwas tut. Framework-Komponenten, die im Browser laufen sollen, brauchen eine client:-Direktive.

Für Redakteure hat MDX Fallen, und mdxjs.com nennt sie:

• Eingerückte Codeblöcke gehen nicht, weil Einrückung zum Verschachteln von Komponenten dient. Codeblöcke werden mit Zäunen geschrieben.
• Autolinks gehen nicht, ein Link braucht seine volle Schreibweise.
• HTML-Kommentare gibt es nicht, an ihre Stelle tritt {/* Kommentar */}.
• Ein Zeichen < oder { im Text muss maskiert werden, sonst liest MDX es als Tag oder Ausdruck. Das trifft gerade Rechtstexte mit Klammern und Vergleichen.
• Text, der mit import oder export beginnt, wird als Programmcode gelesen.

Die Folge ist eine Regel, die ich Kunden empfehle: Prosa bleibt in .md, MDX nur dort, wo wirklich eine Komponente im Text steht. Fehler in MDX sind Build-Fehler mit Zeile, kein stilles Verrutschen, das fällt im Build auf und nicht erst bei den Lesern.

Die Option optimize der MDX-Integration beschleunigt laut Dokumentation den Build, kann aber unmaskiertes HTML erzeugen. Bei Seiten mit interaktiven Teilen prüfe ich nach dem Einschalten alles einzeln. Wo Komponenten ihren Platz im Layout haben, steht auf der Seite für Basel.

#Markdoc als Alternative

@astrojs/markdoc bindet Markdoc ein, ein Format, das nach der Beschreibung auf markdoc.dev bei Stripe für die eigene Produktdokumentation entstand. Tags schreibt man mit {% ... %}, etwa {% aside type="tip" %}. In Astro ordnet die Datei markdoc.config.mjs einem Tag eine .astro-Komponente zu, und die erlaubten Attribute werden mit Typen beschrieben.

Zwei Grenzen aus der Astro-Dokumentation: Markdoc-Dateien (.mdoc) lassen sich nur in Content Collections verwenden, und Tags und Nodes müssen .astro-Dateien sein, Framework-Komponenten also in eine solche Datei verpackt werden. Die Option allowHTML steht standardmäßig auf false, und die Dokumentation warnt davor, sie ohne vertrauenswürdige Quelle einzuschalten.

#Codeblöcke mit Shiki

Für Anleitungen, Schnittstellenbeschreibungen oder Beispieldateien färbt Astro Codeblöcke mit Shiki. Nach der Dokumentation ist github-dark das Standardthema, die Ausgabe nutzt Inline-Styles, braucht kein Stylesheet und kein Client-JavaScript. Ein anderes Thema oder zwei Themen für hell und dunkel stehen unter markdown.shikiConfig. Für zwei Themen kommen CSS-Variablen dazu, bei denen das Präfix .shiki durch .astro-code ersetzt wird.

Die Komponente <Code /> erbt shikiConfig nicht aus der Markdown-Konfiguration, ihre Optionen (theme, wrap, transformers) stehen an der Komponente selbst. Mit markdown.syntaxHighlight.excludeLangs (Standard ['math']) lassen sich Sprachen von der Färbung ausnehmen, die Dokumentation nennt Mermaid.js und D2 als Beispiele. Als Alternative zu Shiki unterstützt Astro Prism.

#Ein langer Text bleibt lesbar: meine Checkliste

Lesbarkeit ist auch ein Zugänglichkeitsthema. Für mehrsprachige Auftritte mit solchen Texten beschreibe ich die Struktur auf der Seite für Zürich, und wer seine Texte weiter in WordPress pflegt, findet den Weg dahin auf der Seite für Wien.

#Vom Briefing bis zur Abnahme

1. Schriftliches Briefing. Sie schicken mir die Adresse Ihrer Website und zwei oder drei Ihrer längsten Texte im Original.
2. Rückfragen schriftlich. Wer schreibt, wer prüft, wo liegen die Texte heute, welche Bausteine kommen vor?
3. Umfang und Annahmen schriftlich. Format je Texttyp (Markdown, MDX, Markdoc), Felder, Plugins, Umzug der Altbestände.
4. Testumgebung zur Abnahme. Sie sehen Ihre eigenen Texte in der neuen Struktur, bevor etwas live geht.
5. Wartung als Option. Updates werden in der Testumgebung geprüft, Stundenkontingente gelten im jeweiligen Monat und werden nicht übertragen.

Grafikdesign, Mockups und Wireframes liefern Sie. Ich baue sie nach, entworfen werden sie bei Ihnen. Das Layout markieren Sie in einer Tabellenvorlage, die ich Ihnen schicke.

#Häufige Fragen zu Markdown und MDX in Astro

#Müssen meine Redakteure Markdown lernen?

Für Überschriften, Absätze, Listen, Links und Tabellen reichen wenige Zeichen, und sie lassen sich in einer Stunde zeigen. Wer das nicht will, schreibt weiter in einem Redaktionssystem, und Astro holt die Texte von dort. Das ist ein anderes Projekt, siehe die Seite zu Headless CMS.

#Wann nehme ich MDX statt Markdown?

Wenn im Text eine Komponente stehen soll, etwa ein Hinweiskasten, ein Rechner oder eine Tabelle, die aus Daten entsteht. Für reine Prosa mit Tabellen und Fußnoten genügt Markdown, und es lässt sich leichter prüfen und weitergeben.

#Ist Markdoc die bessere Wahl für Redakteure?

Nicht pauschal. Markdoc hat eine eigene Syntax für Tags, und die Dokumentation von Astro bindet sie nur in Content Collections ein. Es lohnt sich, wenn Sie schon Markdoc-Texte haben oder die Tags strikt vorgeben wollen. Ich vergleiche beides an einem Ihrer Texte.

#Was passiert mit Fußnoten und Tabellen in Markdown?

Beides gehört nach der Dokumentation zu GitHub-Flavored Markdown und ist in Astro standardmäßig eingeschaltet. Die Beschriftungen der Fußnoten lassen sich im Prozessor auf Deutsch einstellen.

#Muss ich bei eingebetteten Videos in MDX etwas beachten?

Ja. Die LDI NRW schreibt in ihrem Muster für Websites, dass die Datenschutzhinweise bei aktiven Inhalten wie Videoplayern zu ergänzen sind. Ich halte im Umfang fest, welche Komponenten Fremdinhalte laden. Die rechtliche Prüfung liegt bei Ihrer Beratung.

#Kommen Sie für das Projekt nach Bonn?

Nein. Ich arbeite von Gdynia aus und nur schriftlich. Auf Ihrer Seite stehen ein Briefing und Rückfragen, danach Umfang und eine Testumgebung zur Abnahme. Termine am Telefon oder per Video gibt es bei mir nicht. Ihre erste Einschätzung erhalten Sie schriftlich, ohne dass Sie dafür zahlen.

#Schreiben Sie mir

Schicken Sie mir über das Kontaktformular die Adresse Ihrer Website, Ihr Ziel, Ihren Termin und den aktuellen Stack, am besten mit zwei oder drei Ihrer längsten Texte und dem Hinweis, wer sie heute schreibt und womit. Ich lese Ihre Unterlagen, frage schriftlich nach und schicke Ihnen eine erste Einschätzung zu Umfang und Annahmen. Dafür berechne ich nichts. Eignet sich für Ihre Texte ein anderes Werkzeug besser, etwa ein Redaktionssystem, schreibe ich das gleich dazu.