arminazimi/slipway-content

Seiten und Beiträge auf einer Slipway-Website schreiben

Eine Slipway-Website besteht aus Markdown-Dateien mit einem Block Frontmatter. Die Layouts erledigen den Rest: den Titel, die Überschrift, das Inhaltsverzeichnis, das Datum und den Sprachwechsler. Du schreibst das Frontmatter aus dem Schema und den Text in reinem Markdown. Wenn die Site eine AGENTS.md hat, lies sie zuerst; sie hat Vorrang, wo sie von dieser Skill abweicht.

1. Ausgangsbasis ermitteln

Hole die Überprüfungen des Themes einmalig in einen Ordner außerhalb der Site:

git clone --depth 1 https://github.com/arminazimi/slipway "$HOME/.slipway"
cd "$HOME/.slipway" && npm ci && cd -

Führe Abschnitt 6 aus, bevor du etwas änderst, und behalte die Ausgabe. Deine Bearbeitung ist abgeschlossen, wenn sie kein neues Problem und keinen neuen Fund hinzufügt.

2. Layout und Datei auswählen

Du schreibst	layout	Datei
Eine einfache Seite (Über uns, Kontakt)	page	<Ordner>/<Seite>.md, ausgeliefert unter /<Ordner>/<Seite>.html
Eine Dokumentationsseite mit Seitenleiste	doc	beliebiger Ordner, oft docs/<Seite>.md, mit einem permalink
Einen datierten Beitrag	post	_posts/<Datum>-<Slug>.md, wobei <Datum> YYYY-MM-DD ist
Die Startseite	home	index.md

Der Dateiname eines Beitrags ist sein Datum und seine Adresse; um den Titel zu ändern, setze title, benenne die Datei niemals um. Eine doc-Seite wird nur in der Seitenleiste angezeigt, wenn die docs-Liste in _data/navigation.yml auf ihren permalink verweist; füge sie dort in Lesereihenfolge hinzu. Erstelle nicht search.json, feed.xml, sitemap.xml, 404.md, tags.md oder archive.md: sie existieren bereits und haben absichtlich Frontmatter und keinen Text.

Entwürfe, geplante Beiträge und Bearbeitungen eines Beitrags: Ein Entwurf kommt in _drafts/<Slug>.md, ohne Datum im Namen – GitHub Pages baut _drafts/ nie, und jekyll serve --drafts zeigt ihn mit dem heutigen Datum an. Ein geplanter Beitrag ist ein normaler Beitrag, dessen Dateiname mit YYYY-MM-DD in der Zukunft liegt: GitHub Pages veröffentlicht ihn automatisch an diesem Datum, und jekyll serve --future zeigt ihn vorzeitig an, auf der Seite als „Geplant“ markiert. Nach einer wesentlichen Bearbeitung eines veröffentlichten Beitrags füge updated: YYYY-MM-DD hinzu (gleiches Format wie das Datum im Dateinamen): Der Beitrag zeigt es als „bearbeitet am“ an, und der Feed, die Sitemap und die strukturierten Daten melden es als Datum der letzten Änderung.

3. Frontmatter aus dem Schema befüllen

Jeder Schlüssel, sein Typ und seine erlaubten Werte stehen in reference/front-matter.md, generiert aus den Schemas, die die Prüfungen verwenden. Verwende nur Schlüssel, die für dein Layout aufgeführt sind.

• title ist erforderlich und darf nicht leer sein. Das Layout gibt ihn als Seitenüberschrift aus.
• Füge description hinzu: ein Satz für Suchergebnisse und Linkvorschauen.
• tags und categories sind eine Liste: tags: [release, notes].
• author bei einem Beitrag ist ein Schlüssel aus _data/authors.yml, oder eine Liste von Schlüsseln für mehrere Autoren: author: [ada, sam]. Fehlt der Schlüssel in dieser Datei, füge den Autor dort zuerst hinzu.
• series bei einem Beitrag ordnet ihn einer Serie zu: verwende auf jedem Teil denselben Namen, series: Schreiben fürs Web. Die Teile werden nach Datum sortiert.
• permalink beginnt mit /. Lasse ihn bei einem Beitrag in der Standardsprache weg; die Site-Konfiguration legt die Adresse fest.
• Setze lang auf einer Seite, die nicht in der Standardsprache der Site ist (lang in _config.yml), und auf jeder Seite, die eine Übersetzung hat.
• Nur bei home: cta_text und cta_url gehören zusammen oder gar nicht. variant wählt das Aussehen: editorial (Standard), landing (füge features hinzu, jedes mit einem title), blog oder docs (Karten aus der docs-Liste von _data/navigation.yml).
• Setze einen Wert in Anführungszeichen, wenn er : enthält oder mit einem Zeichen beginnt, das YAML besonders behandelt ([, {, *, &, !, #, |, >, @ oder ein Backtick).

4. Textkörper schreiben

• Nur reines Markdown. Niemals Liquid: kein {{ }} und kein {% %}, nicht einmal in einem Codeblock. Die Layouts fügen bereits hinzu, was Liquid tun würde.
• Beginne Abschnitte mit ##. Die h1 ist der Titel; eine #-Überschrift im Textkörper erzeugt eine zweite.
• Halte die Überschriftsebenen in der Reihenfolge (##, dann ###), damit das Inhaltsverzeichnis und der Button „Mit deinem Agenten bearbeiten“ jeden Abschnitt finden.
• Verlinke zu anderen Seiten mit der Adresse, nicht mit der Datei: [Installieren](/docs/install/), [Über uns](/about.html).
• Bilder liegen in assets/; gib jedem einen Alt-Text: ![Ein Diagramm der Build-Zeiten](/assets/build-times.png).
• Für eine breitere Seite setze width: narrow, wide oder full im Frontmatter. Um einen einzelnen Block zu verbreitern (eine Tabelle, ein Bild, eine Abbildung), umschließe ihn mit einem HTML-Element der Klasse sl-wide (bis zu 64rem) oder sl-bleed (randlos): <figure class="sl-wide"><img src="/assets/map.png" alt="Eine Karte der Route"></figure>. Das doc-Layout behält Abschnitte in seiner Spalte.
• Gib Codeblöcken eine Sprache (```yaml), damit sie hervorgehoben werden und in einer rechts-nach-links-Seite von links nach rechts gelesen werden.

Beispiele, die die Schemas erfüllen:

• examples/doc-page.md: eine doc-Seite.
• examples/post.md: ein Beitrag mit Tags.
• examples/post-fa.md: derselbe Beitrag auf Persisch.

Der erste Kommentar in jeder Datei sagt, wohin die Datei gehört.

5. Übersetzung hinzufügen

1. Die Sprache muss in slipway.languages in _config.yml enthalten sein, mit einem code, einem name und einem prefix wie /fa. Fehlt sie, frage, bevor du eine Sprache hinzufügst: das ändert den Sprachwechsler auf jeder Seite.
2. Gib dem Original einen translation_key, falls es keinen hat, z. B. plain-markdown, und sein lang (lang: en), falls es keins hat: der Wechsler findet eine Übersetzung anhand beider. Gib der Übersetzung denselben translation_key. Das verknüpft die beiden im Sprachwechsler und in der Sitemap.
3. Setze lang auf den Sprachcode und permalink auf eine Adresse unter dem Präfix: /fa/plain-markdown/.
4. Wohin die Datei gehört: Eine Seite kommt in den Präfix-Ordner (fa/about.md); ein Beitrag bleibt in _posts/ mit seinem eigenen Slug (_posts/2026-10-20-plain-markdown-fa.md).
5. Übersetze title, description, tags und den Textkörper. Behalte layout, das Datum, Code, Befehle und URLs bei.
6. Wenn die Site ein Headermenü für diese Sprache hat (main_fa in _data/navigation.yml), füge die Seite auch dort hinzu.

Rechts-nach-links-Sprachen (fa, ar, he, ur) erhalten durch lang ein rechts-nach-links-Layout; setze weder direction noch dir. Verwende in persischem Text das persische ی und ک (nicht das arabische ي und ك), einen schmalen geschützten Zwischenraum in Wörtern wie می‌شود und persische Satzzeichen (، und ؟). Setze Befehle, Dateinamen und Code in Backticks: sie bleiben innerhalb des Satzes von links nach rechts.

6. Bearbeitung prüfen

Vom Site-Ordner aus prüfe die Konfiguration und das Frontmatter jeder Seite gegen die Schemas:

node "$HOME/.slipway/tools/theme/validate.mjs" .

Jedes Problem wird als datei:zeile schlüssel: nachricht (erlaubt: ...) ausgegeben. Behebe es in dieser Zeile mit den erlaubten Werten und führe es erneut aus. Baue dann die Site, falls sie eine Gemfile hat:

bundle exec jekyll build

Lies jeden Fehler und jede Warnung und behebe sie in der genannten Datei. Führe dann den Arzt für die Quelle und den Build aus. Er prüft die Site gegen die agentenbearbeitbare Spezifikation: AGENTS.md, content-schemas.json (wenn die Site eine hat, validiert sie dein Frontmatter gegen die darin genannten Schemas), die Quellkarte und die Bearbeitungsaufforderungen:

node "$HOME/.slipway/packages/doctor/bin/slipway.mjs" doctor . --build _site

Vergleiche seine Funde mit deiner Ausgangsbasis. Ein Fund, der deine Datei nennt, liegt in deiner Verantwortung. Ohne Gemfile führe den Arzt ohne --build aus und lies das Log des Pages-Builds nach dem Push.

Niemals

• Niemals Liquid ({{ }} oder {% %}) in einer Seite verwenden.
• Niemals einen Frontmatter-Schlüssel hinzufügen, den reference/front-matter.md nicht aufführt.
• Niemals translation_key nur bei einer Übersetzung ändern; ändere jede Seite, die ihn teilt, oder keine.
• Niemals eine veröffentlichte Seite oder einen veröffentlichten Beitrag umbenennen oder verschieben, um den Titel zu ändern; setze title. Ihre Adresse ist ihr Dateiname oder permalink, und Links darauf würden brechen.
• Niemals _site/ bearbeiten und niemals eine Seite löschen, die Frontmatter und keinen Text hat.
• Niemals Theme-Layouts oder -Includes bearbeiten, um das Aussehen einer Seite zu ändern.