473 lines
15 KiB
Markdown
473 lines
15 KiB
Markdown
# Guide de rédaction
|
||
|
||
Ce guide décrit la création, la mise à jour et la publication des fiches du site **Les Carnets d’Akkadien**.
|
||
|
||
Le principe est le suivant :
|
||
|
||
- le front matter TOML contient les données courtes et structurées ;
|
||
- le corps Markdown contient les explications, exemples, tableaux et commentaires ;
|
||
- tous les champs prévus par le modèle restent présents, même lorsqu’ils sont vides ;
|
||
- les valeurs vides sont généralement omises du rendu.
|
||
|
||
Toutes les commandes sont exécutées depuis la racine du dépôt.
|
||
|
||
## Périmètre des outils
|
||
|
||
Les fiches se trouvent dans cinq sections :
|
||
|
||
| 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` |
|
||
|
||
Les fichiers `_index.md` définissent les sections et restent maintenus manuellement. Les pages autonomes placées directement dans `src/content/`, comme la bibliographie et les mentions légales, ne sont ni créées, ni horodatées, ni validées par les scripts de fiches.
|
||
|
||
Les commandes publiques sont :
|
||
|
||
- `new-content.py` : création d’un brouillon ;
|
||
- `update-content.py` : mise à jour de l’horodatage `updated` ;
|
||
- `check-content.py` : validation structurelle des fiches.
|
||
|
||
`_schema.py` est leur module commun et ne se lance pas directement.
|
||
|
||
## Cycle de rédaction
|
||
|
||
1. créer un brouillon avec `new-content.py` ;
|
||
2. compléter les données et le corps Markdown ;
|
||
3. contrôler son rendu avec les brouillons ;
|
||
4. passer `draft` à `false` lorsqu’il est prêt ;
|
||
5. exécuter les validations et construire la version publique ;
|
||
6. après une modification substantielle ultérieure, actualiser `updated`.
|
||
|
||
Pendant la rédaction :
|
||
|
||
```sh
|
||
zola --root src serve --drafts
|
||
```
|
||
|
||
Avant publication :
|
||
|
||
```sh
|
||
./scripts/check-content.py
|
||
zola --root src check --drafts
|
||
zola --root src build --drafts
|
||
zola --root src build
|
||
```
|
||
|
||
`zola check` contrôle le chargement du site et ses liens. Les deux constructions suivantes vérifient réellement le rendu de tous les brouillons, puis celui de la version publique. En l’absence d’accès réseau, ajouter `--skip-external-links` à la commande `zola check`.
|
||
|
||
## Créer une fiche
|
||
|
||
Syntaxe générale :
|
||
|
||
```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
|
||
```
|
||
|
||
Dans un terminal interactif, l’omission de `--nature` ouvre un menu. Dans un contexte non interactif, l’option est obligatoire.
|
||
|
||
Le générateur :
|
||
|
||
- normalise l’identifiant et le titre en Unicode NFC ;
|
||
- crée tous les champs prévus par le modèle ;
|
||
- initialise la fiche comme brouillon ;
|
||
- refuse d’écraser un fichier existant ;
|
||
- ne renseigne aucune donnée linguistique et ne rédige pas le corps Markdown.
|
||
|
||
Le titre est déduit de l’identifiant pour les articles, la grammaire et les textes. 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. Toute forme, graphie ou 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 taxonomies portent des noms français. Les lectures conservent exactement leur translittération.
|
||
|
||
### Unicode et translittération
|
||
|
||
Les sources sont enregistrées en UTF-8 et utilisent la normalisation Unicode NFC. 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 sert aux commandes, chemins et noms de champs.
|
||
|
||
### Identifiants et noms de fichiers
|
||
|
||
Pour les articles, la grammaire, les textes et le vocabulaire, l’identifiant devient le nom du fichier. Il doit être fourni sans extension et respecter les règles suivantes :
|
||
|
||
- minuscules uniquement ;
|
||
- aucun espace ni underscore ;
|
||
- lettres Unicode, chiffres et tirets seulement ;
|
||
- aucun double tiret ni tiret final.
|
||
|
||
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 un numéro MZL compris entre 1 et 999. Le générateur produit automatiquement un nom sur trois chiffres :
|
||
|
||
```text
|
||
src/content/signes/mzl-001.md
|
||
src/content/signes/mzl-113.md
|
||
src/content/signes/mzl-167.md
|
||
```
|
||
|
||
Zola utilise la stratégie de slugification `safe`, afin de conserver notamment la distinction entre `tim` et `ṭim`.
|
||
|
||
### Taxonomies
|
||
|
||
Les taxonomies publiques sont :
|
||
|
||
- `natures` pour le vocabulaire ;
|
||
- `lectures` pour les signes ;
|
||
- `themes` pour la grammaire ;
|
||
- `genres` pour les textes.
|
||
|
||
Une fiche de vocabulaire contient exactement une nature reconnue, car elle détermine son modèle de champs. Les autres taxonomies peuvent contenir plusieurs termes.
|
||
|
||
Dans `themes` et `genres`, les termes composés utilisent des tirets :
|
||
|
||
```toml
|
||
natures = ["préposition"]
|
||
lectures = ["tim", "ṭim"]
|
||
themes = ["morphologie-nominale"]
|
||
genres = ["inscription-commémorative"]
|
||
```
|
||
|
||
Les templates rétablissent les espaces à l’affichage, tandis que les URL restent sans espace :
|
||
|
||
```text
|
||
/themes/morphologie-nominale/
|
||
/genres/inscription-commémorative/
|
||
```
|
||
|
||
La graphie d’un terme doit rester stable après sa publication.
|
||
|
||
## Front matter commun
|
||
|
||
Chaque fiche créée par le générateur commence par :
|
||
|
||
```toml
|
||
title = "Titre"
|
||
date = 2026-08-06T12:30:00+02:00
|
||
# updated = YYYY-MM-DDTHH:MM:SS+HH:MM
|
||
description = ""
|
||
draft = true
|
||
```
|
||
|
||
- `title` : titre affiché ;
|
||
- `date` : horodatage initial et date de publication ;
|
||
- `updated` : dernière modification substantielle ;
|
||
- `description` : résumé court facultatif ;
|
||
- `draft` : état de publication.
|
||
|
||
`date` et `updated` sont des horodatages TOML sans guillemets, produits dans le fuseau `Europe/Paris`. Chaque fiche doit conserver **exactement une** ligne `updated`, commentée ou active.
|
||
|
||
Pour actualiser une fiche :
|
||
|
||
```sh
|
||
./scripts/update-content.py src/content/vocabulaire/bītum.md
|
||
```
|
||
|
||
La forme relative à `src/content/` est également acceptée :
|
||
|
||
```sh
|
||
./scripts/update-content.py vocabulaire/bītum.md
|
||
```
|
||
|
||
Le script refuse les index, les pages autonomes et les chemins extérieurs aux cinq sections. Il remplace l’unique ligne `updated` par l’heure courante :
|
||
|
||
```toml
|
||
updated = 2026-08-06T16:47:00+02:00
|
||
```
|
||
|
||
Sur la page d’accueil, `updated` prime sur `date` pour le classement des trois fiches récentes. Il ne doit donc être activé qu’après une modification substantielle.
|
||
|
||
### Descriptions automatiques
|
||
|
||
Lorsque `description` reste vide :
|
||
|
||
- une fiche de vocabulaire affiche un résumé construit à partir de sa nature, de son genre et de son sens ;
|
||
- une fiche de signe affiche son titre et son numéro MZL ;
|
||
- les autres fiches n’affichent pas de résumé de remplacement dans leur contenu.
|
||
|
||
Les mêmes résumés automatiques servent de métadescription aux fiches de vocabulaire et de signes. Pour les autres pages sans description spécifique, le template utilise la description générale du site.
|
||
|
||
Une description manuelle reste préférable lorsqu’elle apporte une information plus précise, notamment pour les articles, la grammaire et les textes.
|
||
|
||
### Brouillons
|
||
|
||
Un brouillon peut conserver des valeurs vides, mais tous les champs de son modèle restent présents. Pour publier une fiche :
|
||
|
||
1. compléter les informations disponibles ;
|
||
2. rédiger le corps Markdown ;
|
||
3. vérifier la date souhaitée ;
|
||
4. remplacer `draft = true` par `draft = false` ;
|
||
5. exécuter les contrôles du cycle de rédaction.
|
||
|
||
Une fiche publiée peut repasser temporairement à `draft = true`.
|
||
|
||
## Modèles de contenu
|
||
|
||
Les tables suivantes viennent après les champs communs, dans le même front matter délimité par `+++`.
|
||
|
||
### Vocabulaire
|
||
|
||
Toutes les fiches lexicales contiennent au minimum :
|
||
|
||
```toml
|
||
[extra]
|
||
meaning = ""
|
||
logograms = []
|
||
|
||
[taxonomies]
|
||
natures = ["nature"]
|
||
```
|
||
|
||
`meaning` contient le sens principal ou une courte série de sens. `logograms` est toujours un tableau de chaînes :
|
||
|
||
```toml
|
||
logograms = ["LUGAL"]
|
||
```
|
||
|
||
Chaque nature ajoute les champs suivants :
|
||
|
||
| 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 sont des chaînes, même lorsqu’ils sont vides. Pour un verbe, le titre fournit déjà l’infinitif et celui-ci n’est pas répété dans `[extra]`.
|
||
|
||
Principaux champs :
|
||
|
||
- `gender` : genre grammatical ;
|
||
- `bound` : forme liée ;
|
||
- `plural` : pluriel lexical ;
|
||
- `predicative` : forme 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 ;
|
||
- `value` : valeur numérique.
|
||
|
||
Le corps Markdown reste libre. Rubriques possibles :
|
||
|
||
```markdown
|
||
## Emploi
|
||
## Morphologie
|
||
## Déclinaison
|
||
## Thèmes dérivés
|
||
## Occurrences
|
||
## Voir aussi
|
||
## Sources
|
||
```
|
||
|
||
### Signes
|
||
|
||
Commande :
|
||
|
||
```sh
|
||
./scripts/new-content.py signes 113 --title BE
|
||
```
|
||
|
||
Champs propres :
|
||
|
||
```toml
|
||
[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` contient les trois chiffres du numéro ;
|
||
- `lectures` contient les lectures translittérées.
|
||
|
||
Le validateur vérifie la présence et le type de ces champs, mais ne compare pas `mzl` au nom du fichier.
|
||
|
||
Rubriques possibles :
|
||
|
||
```markdown
|
||
## Valeurs syllabiques
|
||
## Emplois logographiques
|
||
## Emploi comme déterminatif
|
||
## Variantes graphiques
|
||
## Notes
|
||
```
|
||
|
||
Le corps peut rester vide lorsque le front matter suffit.
|
||
|
||
### Grammaire
|
||
|
||
```toml
|
||
[taxonomies]
|
||
themes = []
|
||
```
|
||
|
||
`themes` regroupe les fiches par notion grammaticale. Le corps est organisé librement selon le sujet.
|
||
|
||
### Textes
|
||
|
||
```toml
|
||
[taxonomies]
|
||
genres = []
|
||
```
|
||
|
||
`genres` décrit le type documentaire, par exemple `lettre` ou `inscription-commémorative`.
|
||
|
||
Structure possible :
|
||
|
||
```markdown
|
||
## Présentation
|
||
## Translittération
|
||
## Normalisation
|
||
## Traduction
|
||
## Commentaire philologique
|
||
## Vocabulaire
|
||
```
|
||
|
||
### Articles
|
||
|
||
```toml
|
||
[extra]
|
||
banner = ""
|
||
banner_alt = ""
|
||
banner_credit = ""
|
||
```
|
||
|
||
- `description` est affichée dans la liste des articles, sur l’accueil et dans la page ;
|
||
- `banner` est un chemin relatif à `src/static/`, par exemple `images/articles/article.webp` ;
|
||
- `banner_alt` contient le texte alternatif ;
|
||
- `banner_credit` contient une attribution ou une légende facultative.
|
||
|
||
Lorsque `banner` est vide, aucune image n’est générée. Lorsqu’il est renseigné, le template lit les dimensions du fichier avec Zola et les ajoute au HTML. Une image informative doit avoir un texte alternatif utile ; une image purement décorative peut utiliser une chaîne vide.
|
||
|
||
## Markdown et ressources
|
||
|
||
### Liens internes
|
||
|
||
Les liens vers d’autres contenus utilisent la syntaxe interne 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.
|
||
|
||
### Blocs de code
|
||
|
||
Un bloc délimité par trois accents graves et associé à une langue reçoit automatiquement la coloration syntaxique :
|
||
|
||
````markdown
|
||
```python
|
||
print("šulmu")
|
||
```
|
||
````
|
||
|
||
Zola génère `giallo.css`, tandis que le HTML rendu utilise les classes correspondantes. Cette feuille est produite pendant la construction et ne doit pas être modifiée ou ajoutée aux sources.
|
||
|
||
## Ce que contrôle le validateur
|
||
|
||
`check-content.py` contrôle uniquement les fiches des cinq sections. Il ignore les fichiers `_index.md` et les pages placées directement dans `src/content/`.
|
||
|
||
Pour chaque fiche, il vérifie :
|
||
|
||
- la lecture en UTF-8 ;
|
||
- la présence d’un front matter délimité par `+++` ;
|
||
- la validité du TOML ;
|
||
- exactement une ligne `updated`, commentée ou active ;
|
||
- `title` et `description` de type chaîne ;
|
||
- `date` de type horodatage TOML ;
|
||
- `draft` de type booléen ;
|
||
- `updated`, lorsqu’il est actif, de type horodatage TOML.
|
||
|
||
Pour le vocabulaire, il vérifie également :
|
||
|
||
- exactement une nature grammaticale reconnue ;
|
||
- tous les champs `[extra]` prévus pour cette nature ;
|
||
- des chaînes pour les champs simples ;
|
||
- un tableau de chaînes pour `logograms`.
|
||
|
||
Pour les autres sections, il vérifie :
|
||
|
||
- `banner`, `banner_alt` et `banner_credit` pour les articles ;
|
||
- `themes` pour la grammaire ;
|
||
- `sign`, `mzl` et `lectures` pour les signes ;
|
||
- `genres` pour les textes.
|
||
|
||
Par convention, les termes composés de `themes` et `genres` utilisent des tirets. Cette convention relève de la rédaction et n’est pas contrôlée par le validateur.
|
||
|
||
Le validateur accepte les chaînes et tableaux vides. Il ne contrôle pas :
|
||
|
||
- la qualité ou l’exactitude linguistique des valeurs ;
|
||
- les champs supplémentaires ;
|
||
- la forme des noms de fichiers ;
|
||
- la correspondance entre le numéro MZL et le nom du fichier ;
|
||
- la normalisation Unicode des fichiers existants.
|
||
|
||
Zola reste responsable des liens, taxonomies et templates. Le générateur reste responsable de produire des noms de fichiers valides et des squelettes complets.
|
||
|
||
## Vérification avant publication
|
||
|
||
Avant de publier ou déployer :
|
||
|
||
- conserver tous les champs du modèle, même vides ;
|
||
- conserver exactement une ligne `updated` ;
|
||
- utiliser `draft = false` uniquement pour un contenu prêt ;
|
||
- utiliser des tirets dans les thèmes et genres composés ;
|
||
- éviter les rubriques vides et les textes d’attente ;
|
||
- lancer `update-content.py` seulement après une modification substantielle ;
|
||
- exécuter le validateur, `zola check`, la construction avec brouillons, puis la construction publique.
|