# Guide de rédaction Ce guide explique comment créer, compléter, mettre à jour et publier les contenus de **Les Carnets d’Akkadien**. Le principe général est simple : - le front matter TOML contient les données brèves et structurées ; - le corps Markdown contient les explications, tableaux, exemples et commentaires ; - les champs prévus par un modèle restent présents, même lorsqu’ils sont vides ; - les champs optionnels vides sont généralement omis du rendu ; les champs structurels restent néanmoins présents dans le front matter. Toutes les commandes sont exécutées depuis la racine du dépôt. ## Organisation des contenus | Type | Répertoire | Taxonomie | |---|---|---| | Article | `src/content/articles/` | aucune | | Grammaire | `src/content/grammaire/` | `themes` | | Signe | `src/content/signes/` | `lectures` | | Texte | `src/content/textes/` | `genres` | | Vocabulaire | `src/content/vocabulaire/` | `natures` | La bibliographie et les mentions légales sont des pages autonomes placées directement dans `src/content/`. Les trois scripts de fiches ne les créent, ne les modifient et ne les valident pas. Chaque section contient un fichier `_index.md` qui définit son titre, sa description, son tri et ses templates. Ces index sont maintenus manuellement ; le générateur crée uniquement des pages de contenu. ## Cycle de rédaction 1. créer un brouillon avec `new-content.py` ; 2. compléter le front matter et le corps Markdown ; 3. vérifier localement la fiche avec les brouillons affichés ; 4. passer `draft` à `false` lorsque la fiche est prête ; 5. lancer le validateur et la vérification Zola ; 6. après une modification substantielle ultérieure, actualiser `updated` avec `update-content.py`. Afficher les brouillons localement : ```sh zola --root src serve --drafts ``` Contrôler la structure des fiches et la construction du site avant publication : ```sh ./scripts/check-content.py zola --root src check --drafts --skip-external-links ``` ## Créer une fiche La commande générale est : ```sh ./scripts/new-content.py SECTION IDENTIFIANT [--nature NATURE] [--title TITRE] ``` Exemples : ```sh ./scripts/new-content.py vocabulaire šarrum --nature nom ./scripts/new-content.py vocabulaire epēšum --nature verbe ./scripts/new-content.py vocabulaire --nature particule -- -ma ./scripts/new-content.py signes 113 --title BE ./scripts/new-content.py grammaire suffixes-pronominaux ./scripts/new-content.py textes lettre-au-marchand ./scripts/new-content.py articles nouvel-article ``` Pour le vocabulaire, les natures reconnues sont : ```text nom, adjectif, verbe, pronom, préposition, adverbe, conjonction, particule, numéral ``` Lorsque `--nature` est omise dans un terminal interactif, le générateur propose un menu. Elle est obligatoire dans un contexte non interactif. Le générateur normalise l’identifiant et le titre en Unicode NFC, prépare tous les champs nécessaires et refuse d’écraser un fichier existant. Il ne renseigne pas les données linguistiques et ne rédige pas le corps Markdown. Pour un article, un texte ou une note de grammaire, le titre est déduit de l’identifiant en remplaçant les tirets par des espaces et en mettant l’initiale en majuscule. Pour le vocabulaire, il reprend l’identifiant. Pour un signe, il reste vide sauf si `--title` est fourni. ## Conventions générales ### Période et terminologie Le site est principalement consacré au paléo-babylonien. Une forme, une graphie ou une analyse relevant d’une autre période ou d’un autre dialecte est signalée dans la fiche concernée. Les clés du front matter sont en anglais. Les noms des taxonomies sont en français ; leurs termes suivent la donnée affichée, en français pour les catégories et en translittération pour les lectures. ### Unicode et translittération Tous les fichiers de contenu sont enregistrés en UTF-8 et normalisés en Unicode NFC, y compris leurs noms. Les lemmes, lectures et formes akkadiennes conservent leurs diacritiques : ```text bītum parāsum aš ṭim ``` Dans le corps Markdown, les formes linguistiques sont généralement écrites en *italique*. Le code en ligne est réservé aux commandes, chemins et noms de champs. ### Noms de fichiers Pour les articles, la grammaire, les textes et le vocabulaire, l’identifiant fourni au générateur devient le nom du fichier. Il doit être écrit sous sa forme finale : - en minuscules ; - sans espace ni underscore ; - avec seulement des lettres Unicode, des chiffres et des tirets ; - sans double tiret ni tiret final ; - sans extension `.md`. Exemples : ```text src/content/vocabulaire/bītum.md src/content/vocabulaire/parāsum.md src/content/grammaire/forme-liee.md src/content/articles/les-carnets-sont-en-ligne.md ``` Un tiret initial est accepté uniquement pour le vocabulaire, par exemple `-ma.md`. Les signes utilisent toujours un numéro MZL sur trois chiffres : ```text src/content/signes/mzl-001.md src/content/signes/mzl-113.md src/content/signes/mzl-167.md ``` Les chemins et les termes de taxonomie utilisent la stratégie de slugification `safe` de Zola. Les diacritiques sont donc conservés : `tim` et `ṭim` restent distincts. ## Front matter commun Le générateur place les éléments suivants en tête de chaque fiche : ```toml title = "Titre" date = 2026-08-05T12:30:00+02:00 # updated = YYYY-MM-DDTHH:MM:SS+HH:MM description = "" draft = true ``` Les tables propres au type de contenu viennent ensuite dans le même front matter. - `title` est le titre affiché ; - `date` est l’horodatage initial de la fiche et sert de date de publication ; - `updated` est l’horodatage de la dernière modification substantielle ; - `description` est un résumé court, rédigé manuellement lorsqu’il est utile ; - `draft` détermine si la page est publiée. `date` est un horodatage TOML sans guillemets, créé dans le fuseau `Europe/Paris`. La fiche doit toujours conserver exactement une ligne `updated`, commentée ou active. Après une modification substantielle, lancer : ```sh ./scripts/update-content.py src/content/vocabulaire/bītum.md ``` La forme abrégée, relative à `src/content/`, est également acceptée : ```sh ./scripts/update-content.py vocabulaire/bītum.md ``` Le chemin complet peut être saisi rapidement avec l’autocomplétion du shell. Le script accepte uniquement les fiches Markdown placées dans une section connue ; il refuse donc les index, les pages situées directement dans `src/content/` et les fichiers extérieurs à ce répertoire. Il remplace ensuite l’unique ligne `updated` par l’heure courante de `Europe/Paris` : ```toml updated = 2026-08-05T16:47:00+02:00 ``` Sur la page d’accueil, `updated` prime sur `date` pour classer les « Fiches récentes ». Il ne doit donc être activé qu’après une modification substantielle. Lorsque `description` reste vide : - une fiche de vocabulaire affiche une phrase construite à partir de sa nature, de son genre et de son sens ; - une fiche de signe affiche une phrase construite à partir de son titre et de son numéro MZL ; - un article, une note de grammaire ou un texte n’affiche pas de résumé de remplacement. La métadescription HTML utilise alors, en dernier recours, la description générale du site. ## Brouillons et publication Un brouillon peut conserver des valeurs vides, mais tous les champs de son modèle restent présents afin que sa structure puisse être vérifiée dès sa création. Pour publier une fiche : 1. compléter les données disponibles sans supprimer les champs de son modèle ; 2. rédiger le corps Markdown ; 3. vérifier que `date` correspond à la publication souhaitée ; 4. remplacer `draft = true` par `draft = false` ; 5. lancer les contrôles indiqués dans le cycle de rédaction. Une fiche temporairement retirée du site peut repasser à `draft = true`. ## Taxonomies Les taxonomies publiques sont : - `natures` pour la nature grammaticale du vocabulaire ; - `lectures` pour les lectures des signes ; - `themes` pour les notions grammaticales ; - `genres` pour les types documentaires des textes. Les termes sont écrits sous leur forme destinée à l’affichage : ```toml natures = ["préposition"] lectures = ["tim", "ṭim"] themes = ["morphologie nominale"] genres = ["lettre"] ``` La graphie doit rester stable. Une fiche de vocabulaire contient exactement une nature connue, car cette valeur sélectionne le modèle de champs à contrôler. Les autres taxonomies peuvent contenir plusieurs termes lorsque cela est pertinent. ## Fiches de vocabulaire Toutes les fiches lexicales utilisent la structure générale suivante : ```toml +++ title = "lemme" date = 2026-08-05T12:30:00+02:00 # updated = YYYY-MM-DDTHH:MM:SS+HH:MM description = "" draft = true [extra] meaning = "" logograms = [] [taxonomies] natures = ["nature"] +++ ``` `meaning` contient le sens principal ou une courte série de sens. Il est normalement renseigné avant publication, mais peut rester vide pendant la rédaction. `logograms` reste toujours un tableau de chaînes : ```toml logograms = ["LUGAL"] ``` Chaque nature ajoute les champs suivants, dans l’ordre produit par le générateur : | Nature | Champs supplémentaires | |---|---| | Nom | `gender`, `bound`, `plural` | | Adjectif | `bound`, `feminine`, `masculine_plural`, `feminine_plural`, `predicative` | | Verbe | `root`, `stem`, `verb_class`, `vowel_class`, `preterite`, `durative`, `perfect`, `imperative`, `participle`, `verbal_adjective` | | Pronom | `pronoun_type`, `person`, `gender`, `number` | | Préposition | `governs` | | Adverbe | `function` | | Conjonction | `function` | | Particule | `function` | | Numéral | `numeral_type`, `value`, `gender`, `feminine` | Tous les champs simples restent des chaînes, même lorsqu’ils sont vides. Chaque fiche, brouillon compris, doit conserver tous les champs prévus pour sa nature. Le validateur contrôle leur présence et leur type, sans imposer de valeur non vide ni refuser d’éventuels champs supplémentaires. Pour un verbe, le titre fournit déjà l’infinitif et celui-ci n’est donc pas répété dans `[extra]`. ### Sens des principaux champs - `gender` : genre grammatical ; - `bound` : forme liée ; - `plural` : pluriel lexical ; - `predicative` : forme prédicative de référence, affichée comme « Prédicatif (3 m. s.) » ; - `root` : racine, par exemple `p-r-s` ; - `stem` : thème verbal, par exemple `G`, `D`, `Š` ou `N` ; - `verb_class` : classe morphologique, par exemple `fort`, `I-n` ou `III-faible` ; - `vowel_class` : classe vocalique, par exemple `a/u` ; - `pronoun_type` : type de pronom ; - `governs` : cas régi par une préposition ; - `function` : fonction d’un adverbe, d’une conjonction ou d’une particule ; - `numeral_type` : cardinal, ordinal ou autre type de numéral ; - `value` : valeur numérique. Le corps Markdown reste libre. Les rubriques suivantes peuvent servir de repères lorsqu’elles sont utiles : ```markdown ## Emploi ## Morphologie ## Déclinaison ## Thèmes dérivés ## Occurrences ## Voir aussi ## Sources ``` Les paradigmes, exceptions, constructions et commentaires détaillés appartiennent au corps plutôt qu’au front matter. Les rubriques vides ne sont pas ajoutées. ## Fiches de signes La commande suivante : ```sh ./scripts/new-content.py signes 113 --title BE ``` produit : ```toml +++ title = "BE" date = 2026-08-05T12:30:00+02:00 # updated = YYYY-MM-DDTHH:MM:SS+HH:MM description = "" draft = true [extra] sign = "" mzl = "113" [taxonomies] lectures = [] +++ ``` - le fichier est nommé `mzl-113.md` ; - `title` contient le nom usuel du signe ; - `sign` contient le caractère cunéiforme Unicode ; - `mzl` reprend exactement les trois chiffres du nom de fichier ; - `lectures` contient les lectures translittérées. Le générateur forme automatiquement le nom `mzl-XXX.md` et renseigne le numéro MZL correspondant. Le validateur vérifie ensuite que `sign`, `mzl` et `lectures` restent présents avec le type attendu, même lorsque la fiche est en brouillon. Il n’impose pas de valeur non vide et ne compare pas le numéro au nom du fichier. Le corps peut accueillir, selon le besoin : ```markdown ## Valeurs syllabiques ## Emplois logographiques ## Emploi comme déterminatif ## Variantes graphiques ## Notes ``` Une fiche de signe peut rester sans corps si son front matter suffit. ## Notes de grammaire ```toml +++ title = "Titre de la fiche" date = 2026-08-05T12:30:00+02:00 # updated = YYYY-MM-DDTHH:MM:SS+HH:MM description = "" draft = true [taxonomies] themes = [] +++ ``` `themes` regroupe les fiches par notion grammaticale. Le corps est organisé librement selon le sujet. ## Textes étudiés ```toml +++ title = "Titre du texte" date = 2026-08-05T12:30:00+02:00 # updated = YYYY-MM-DDTHH:MM:SS+HH:MM description = "" draft = true [taxonomies] genres = [] +++ ``` `genres` décrit le type documentaire, par exemple `lettre` ou `inscription commémorative`. Une structure fréquente est : ```markdown ## Présentation ## Translittération ## Normalisation ## Traduction ## Commentaire philologique ## Vocabulaire ``` Elle peut être adaptée à chaque texte. ## Articles ```toml +++ title = "Titre de l’article" date = 2026-08-05T12:30:00+02:00 # updated = YYYY-MM-DDTHH:MM:SS+HH:MM description = "" draft = true [extra] banner = "" banner_alt = "" banner_credit = "" +++ ``` - `description` est affichée dans la liste des articles, sur la page d’accueil et dans la page elle-même ; - `banner` indique un chemin relatif à `src/static/`, par exemple `images/articles/article.webp` ; - `banner_alt` contient le texte alternatif de l’image ; - `banner_credit` contient une attribution ou une légende facultative. Lorsque `banner` reste vide, aucune image ni aucun espace réservé ne sont générés. Lorsqu’une image est ajoutée, son texte alternatif doit décrire utilement son contenu ; une image purement décorative peut utiliser une chaîne vide. ## Liens internes Les liens entre contenus utilisent les chemins internes de Zola : ```markdown [Voir bītum](@/vocabulaire/bītum.md) [Voir la forme liée](@/grammaire/forme-liee.md) ``` Ils sont ajoutés lorsqu’ils apportent un contexte réel : occurrence dans un texte, exemple grammatical, signe observé ou relation lexicale utile. ## Ce que contrôle le validateur Le validateur est volontairement limité à la structure des fiches placées dans `articles/`, `grammaire/`, `signes/`, `textes/` et `vocabulaire/`. Les pages situées directement dans `src/content/`, comme la bibliographie et les mentions légales, ainsi que les fichiers `_index.md`, sont entièrement ignorés. Pour chaque fiche, il vérifie que le fichier peut être lu en UTF-8, que son front matter TOML est valide et qu’il contient exactement une ligne `updated`, commentée ou active. Il contrôle ensuite la présence et le type des champs communs : - `title` et `description` doivent être des chaînes, éventuellement vides ; - `date` doit être un horodatage TOML ; - `draft` doit être un booléen ; - `updated`, lorsqu’il est actif, doit également être un horodatage TOML. Les brouillons et les fiches publiées sont contrôlés de la même façon. Le validateur n’évalue pas la qualité éditoriale des valeurs et n’exige donc ni titre, ni sens, ni thème verbal non vide. La nature grammaticale unique et connue sert seulement à déterminer le modèle lexical applicable. Pour le vocabulaire, il vérifie en plus : - la présence d’une seule nature grammaticale connue dans `taxonomies.natures` ; - la présence de tous les champs `[extra]` prévus pour cette nature ; - des chaînes pour les champs simples ; - un tableau de chaînes pour `logograms`, qui peut être vide. Pour les autres sections, il vérifie les modèles centralisés dans `_schema.py` : - `banner`, `banner_alt` et `banner_credit` pour les articles ; - `themes` pour la grammaire ; - `sign`, `mzl` et `lectures` pour les signes ; - `genres` pour les textes. Les tableaux peuvent être vides et les chaînes peuvent être vides. Les champs supplémentaires ne sont pas rejetés. Le validateur ne contrôle ni la forme des noms de fichiers, ni la correspondance du numéro MZL avec le fichier, ni la normalisation Unicode du chemin ou du contenu. Zola reste responsable de la construction, des liens internes, des taxonomies et du rendu des templates. Le générateur reste responsable de produire les noms de fichiers attendus et des squelettes complets. ## Principes de cohérence - conserver tous les champs prévus par le modèle, même vides ; - conserver exactement une ligne `updated`, commentée ou active ; - ne renseigner que des informations établies ou utiles ; - garder une graphie stable pour chaque lemme, lecture et terme de taxonomie ; - employer `draft = true` pour un contenu incomplet ou temporairement hors ligne ; - exécuter `update-content.py` uniquement après une modification substantielle ; - éviter de répéter dans le corps une donnée déjà claire dans le front matter, sauf lorsqu’une explication apporte quelque chose ; - rédiger des descriptions courtes et informatives lorsqu’un résumé spécifique est utile ; - ne pas ajouter de rubriques vides ni de textes d’attente.