arminazimi/slipway-content

Rédiger des pages et des articles sur un site Slipway

Un site Slipway est constitué de fichiers Markdown avec un bloc de front matter. Les dispositions (layouts) font le reste : le titre, l'en-tête, la table des matières, la date et le sélecteur de langue. Vous rédigez le front matter à partir du schéma et le contenu en Markdown simple. Si le site possède un fichier AGENTS.md, lisez-le d'abord ; il prévaut là où il diffère de cette compétence.

1. Établir une base de référence

Obtenez les vérifications du thème une fois, dans un dossier en dehors du site :

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

Exécutez la section 6 avant de modifier quoi que ce soit et conservez la sortie. Votre modification est terminée lorsqu'elle n'ajoute ni problème ni constatation.

2. Choisir la disposition et le fichier

Vous rédigez	layout	Fichier
Une page simple (à propos, contact)	page	<dossier>/<page>.md, servie à /<dossier>/<page>.html
Une page de documentation avec la barre latérale	doc	n'importe quel dossier, souvent docs/<page>.md, avec un permalink
Un article daté	post	_posts/<date>-<slug>.md, où <date> est YYYY-MM-DD
La page d'accueil	home	index.md

Le nom du fichier d'un article correspond à sa date et à son adresse ; pour changer le titre, définissez title, ne renommez jamais le fichier. Une page doc apparaît dans la barre latérale uniquement lorsque la liste docs dans _data/navigation.yml pointe vers son permalink ; ajoutez-la là dans l'ordre de lecture. Ne créez pas search.json, feed.xml, sitemap.xml, 404.md, tags.md ou archive.md : ils existent déjà, et ils ont intentionnellement un front matter et aucun texte.

Brouillons, articles programmés et modifications sur un article : un brouillon va dans _drafts/<slug>.md, sans date dans son nom — GitHub Pages ne construit jamais _drafts/, et jekyll serve --drafts le prévisualise avec la date du jour. Un article programmé est un article normal dont le nom de fichier YYYY-MM-DD est dans le futur : GitHub Pages le publie automatiquement à cette date, et jekyll serve --future le prévisualise en avance, marqué « Programmé » sur la page. Après une modification substantielle d'un article publié, ajoutez updated: YYYY-MM-DD (même forme que la date du nom de fichier) : l'article affiche « édité le », et le flux, le plan du site et les données structurées le signalent comme date de dernière modification.

3. Remplir le front matter à partir du schéma

Chaque clé, son type et ses valeurs autorisées se trouvent dans reference/front-matter.md, généré à partir des schémas utilisés par les vérifications. Utilisez uniquement les clés qu'il liste pour votre disposition.

• title est requis et ne doit pas être vide. La disposition l'affiche comme en-tête de page.
• Ajoutez description : une phrase pour les résultats de recherche et les aperçus de liens.
• tags et categories sont une liste : tags: [release, notes].
• author sur un article est une clé de _data/authors.yml, ou une liste de clés pour plusieurs auteurs : author: [ada, sam]. Si la clé manque dans ce fichier, ajoutez d'abord l'auteur là-bas.
• series sur un article l'insère dans une série : utilisez exactement le même nom sur chaque partie, series: Écrire pour le web. Les parties sont ordonnées par date.
• permalink commence par /. Laissez-le de côté sur un article dans la langue par défaut ; la configuration du site définit l'adresse.
• Définissez lang sur une page qui n'est pas dans la langue par défaut du site (lang dans _config.yml), et sur chaque page qui a une traduction.
• home uniquement : cta_text et cta_url vont ensemble, ou pas du tout. variant choisit l'apparence : editorial (par défaut), landing (ajoutez features, chacune avec un title), blog ou docs (cartes provenant de la liste docs de _data/navigation.yml).
• Mettez entre guillemets une valeur qui contient : ou commence par un caractère que YAML traite spécialement ([, {, *, &, !, #, |, >, @ ou un backtick).

4. Rédiger le corps

• Markdown simple uniquement. Jamais de Liquid : ni {{ }} ni {% %}, même dans un bloc de code. Les dispositions ajoutent déjà ce que Liquid ferait.
• Commencez les sections par ##. Le h1 est le titre ; un en-tête # dans le corps en crée un second.
• Gardez les niveaux d'en-tête dans l'ordre (##, puis ###), afin que la table des matières et le bouton « Modifier avec votre agent » trouvent chaque section.
• Liez vers d'autres pages par adresse, pas par fichier : [Installation](/docs/install/), [À propos](/about.html).
• Les images se trouvent dans assets/ ; donnez à chacune un texte alternatif : ![Un graphique des temps de construction](/assets/build-times.png).
• Pour une page plus large, définissez width: narrow, wide ou full dans le front matter. Pour élargir un seul bloc (un tableau, une image, une figure), enveloppez-le dans un élément HTML avec la classe sl-wide (jusqu'à 64 rem) ou sl-bleed (bord à bord) : <figure class="sl-wide"><img src="/assets/map.png" alt="Une carte de l'itinéraire"></figure>. La disposition doc garde les sections dans sa colonne.
• Donnez aux blocs de code un langage (```yaml), afin qu'ils soient mis en évidence et lus de gauche à droite dans une page de droite à gauche.

Exemples qui passent les schémas :

• examples/doc-page.md : une page doc.
• examples/post.md : un article avec des tags.
• examples/post-fa.md : le même article en persan.

Le premier commentaire de chacun indique où va le fichier.

5. Ajouter une traduction

1. La langue doit être dans slipway.languages dans _config.yml, avec un code, un name et un prefix tel que /fa. Si elle manque, demandez avant d'ajouter une langue : cela change le sélecteur de chaque page.
2. Donnez à l'original un translation_key s'il n'en a pas, par exemple plain-markdown, et son lang (lang: en) s'il n'en a pas : le sélecteur trouve une traduction par les deux. Donnez à la traduction le même translation_key. Cela lie les deux dans le sélecteur de langue et le plan du site.
3. Définissez lang sur le code de la langue, et permalink sur une adresse sous le préfixe : /fa/plain-markdown/.
4. Où va le fichier : une page va dans le dossier du préfixe (fa/about.md) ; un article reste dans _posts/ avec son propre slug (_posts/2026-10-20-plain-markdown-fa.md).
5. Traduisez title, description, tags et le corps. Conservez layout, la date, le code, les commandes et les URL tels quels.
6. Si le site a un menu d'en-tête pour cette langue (main_fa dans _data/navigation.yml), ajoutez-y également la page.

Les langues de droite à gauche (fa, ar, he, ur) obtiennent une disposition de droite à gauche à partir de lang ; ne définissez pas direction ou dir. En texte persan, utilisez les caractères persans ی et ک (pas les arabes ي et ك), un espace de largeur nulle dans des mots comme می‌شود, et la ponctuation persane (، et ؟). Mettez les commandes, les noms de fichiers et le code entre backticks : ils restent de gauche à droite à l'intérieur de la phrase.

6. Vérifier la modification

Depuis le dossier du site, vérifiez la configuration et le front matter de chaque page par rapport aux schémas :

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

Chaque problème est imprimé sous la forme fichier:ligne clé: message (autorisé: ...). Corrigez-le à cette ligne, en utilisant les valeurs autorisées, et réexécutez. Ensuite, construisez le site, s'il a un Gemfile :

bundle exec jekyll build

Lisez chaque erreur et avertissement et corrigez-les dans le fichier qu'ils nomment. Exécutez ensuite le docteur sur la source et la construction. Il vérifie le site par rapport aux spécifications modifiables par l'agent : AGENTS.md, content-schemas.json (lorsque le site en a un, il valide votre front matter par rapport aux schémas qu'il nomme), la carte source et les invites de modification :

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

Comparez ses constatations avec votre base de référence. Une constatation qui nomme votre fichier est à vous de corriger. Sans Gemfile, exécutez le docteur sans --build et lisez le journal de la construction Pages après avoir effectué un push.

Jamais

• Ne mettez jamais de Liquid ({{ }} ou {% %}) dans une page.
• N'ajoutez jamais une clé de front matter que reference/front-matter.md ne liste pas.
• Ne modifiez jamais translation_key sur une seule traduction ; modifiez chaque page qui le partage, ou aucune.
• Ne renommez ni ne déplacez jamais une page ou un article publié pour changer son titre ; définissez title. Son adresse est son nom de fichier ou permalink, et les liens vers elle seraient rompus.
• Ne modifiez jamais _site/, et ne supprimez jamais une page qui a un front matter et aucun texte.
• Ne modifiez jamais les dispositions ou les inclusions du thème pour changer l'apparence d'une seule page.