julien/lescarnetsdakkadien.netig.net
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Meilleure répartition de la documentation

Browse Source
This commit is contained in:
julien
2026-08-05 18:38:45 +02:00
parent 81616e11e3
commit cc1b03b78e
2 changed files with 111 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files
GUIDE_REDACTION.md
+97 -86
View File
@@ -1,14 +1,16 @@
# Guide de rédaction
Ce guide décrit la manière d’ajouter et de maintenir les contenus du site **Les Carnets d’Akkadien**.
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 le suivant :
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 vides ne sont pas affichés sur le site.
Toutes les commandes sont exécutées depuis la racine du dépôt.
## Organisation des contenus
| Type | Répertoire | Taxonomie |
@@ -21,7 +23,62 @@ Le principe général est le suivant :
La bibliographie et les mentions légales sont des pages autonomes placées directement dans `src/content/`.
Chaque section contient un fichier `_index.md` qui définit son titre, sa description, son tri et ses templates. Ces fichiers sont maintenus manuellement ; le générateur crée uniquement des pages de contenu.
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 les contenus 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
@@ -29,7 +86,7 @@ Chaque section contient un fichier `_index.md` qui définit son titre, sa descri
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 champs structurés propres aux fiches utilisent des clés anglaises. 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.
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
@@ -75,9 +132,11 @@ src/content/signes/mzl-113.md
src/content/signes/mzl-167.md
```
### Front matter commun
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.
Le générateur place les éléments communs suivants en tête du front matter :
## Front matter commun
Le générateur place les éléments suivants en tête de chaque fiche :
```toml
title = "Titre"
@@ -87,22 +146,35 @@ description = ""
draft = true
```
Les tables propres à chaque type de contenu viennent ensuite dans le même front matter.
Les tables propres au type de contenu viennent ensuite dans le même front matter.
- `title` est le titre affiché ;
- `date` est créée dans le fuseau `Europe/Paris` et doit refléter la date de publication ;
- `date` est l’horodatage 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 écrit sans guillemets dans le fuseau `Europe/Paris`. La ligne commentée `# updated = YYYY-MM-DDTHH:MM:SS+HH:MM` est un repère inactif. Après une modification substantielle, `update-content.py` remplace l’unique ligne `updated`, qu’elle soit commentée ou active, par l’horodatage courant. La fiche doit toujours conserver exactement une telle ligne.
`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.
Le résultat utilise le même format que `date` :
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 refuse les index et les fichiers extérieurs à `src/content/`, puis remplace l’unique ligne `updated` par l’heure courante de `Europe/Paris` :
```toml
updated = 2026-08-05T16:47:00+02:00
```
Lorsqu’il est actif, `updated` détermine la position de la fiche dans le bloc « Fiches récentes » de la page d’accueil. En son absence, la date de publication est utilisée.
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 :
@@ -112,75 +184,17 @@ Lorsque `description` reste vide :
La métadescription HTML utilise alors, en dernier recours, la description générale du site.
### Brouillons et publication
## Brouillons et publication
Un brouillon peut rester incomplet et être affiché localement avec :
```sh
zola --root src serve --drafts
```
Pour publier une fiche :
Un brouillon peut rester incomplet. 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 la date ;
4. passer `draft` à `false` ;
5. lancer les contrôles.
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.
```sh
./scripts/check-content.py
zola --root src check --drafts --skip-external-links
```
## Générateur de fiches
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 NFC, prépare tous les champs nécessaires et refuse tout écrasement. 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.
## Horodatage des mises à jour
Après une modification substantielle, lancer :
```sh
./scripts/update-content.py src/content/vocabulaire/bītum.md
```
Le chemin complet se sélectionne rapidement avec la touche Tab du shell. Une forme abrégée relative à `src/content/` est aussi acceptée :
```sh
./scripts/update-content.py vocabulaire/bītum.md
```
Le script refuse les index et les fichiers extérieurs à `src/content/`. Il exige exactement une ligne `updated`, commentée ou active, puis la remplace sans modifier le reste du fichier.
Une fiche temporairement retirée du site peut repasser à `draft = true`.
## Taxonomies
@@ -200,13 +214,11 @@ themes = ["morphologie nominale"]
genres = ["lettre"]
```
La graphie doit rester stable. Les diacritiques sont conservés dans les URL : `tim` et `ṭim` correspondent donc à deux lectures distinctes.
Une fiche de vocabulaire contient exactement une nature. Les autres taxonomies peuvent contenir plusieurs termes lorsque cela est pertinent.
La graphie doit rester stable. Une fiche de vocabulaire contient exactement une nature. Les autres taxonomies peuvent contenir plusieurs termes lorsque cela est pertinent.
## Fiches de vocabulaire
Toutes les fiches lexicales utilisent la même structure générale :
Toutes les fiches lexicales utilisent la structure générale suivante :
```toml
+++
@@ -227,7 +239,7 @@ natures = ["nature"]
`meaning` contient le sens principal ou une courte série de sens. Il doit être renseigné avant publication.
`logograms` contient les écritures logographiques associées au lemme. Il reste toujours un tableau de chaînes :
`logograms` reste toujours un tableau de chaînes :
```toml
logograms = ["LUGAL"]
@@ -247,9 +259,7 @@ Chaque nature ajoute les champs suivants, dans l’ordre produit par le généra
| Particule | `function` |
| Numéral | `numeral_type`, `value`, `gender`, `feminine` |
Tous les champs simples restent des chaînes, même lorsqu’ils sont vides. Une fiche publiée doit contenir exactement les champs de sa nature : un champ manquant, supplémentaire ou mal typé est rejeté par le validateur.
Pour un verbe, `stem` est obligatoire avant publication. Le titre fournit déjà l’infinitif et ne le répète donc pas dans `[extra]`.
Tous les champs simples restent des chaînes, même lorsqu’ils sont vides. Une fiche publiée doit contenir exactement les champs de sa nature. Pour un verbe, `stem` doit être renseigné avant publication. Le titre fournit déjà l’infinitif et ne le répète donc pas dans `[extra]`.
### Sens des principaux champs
@@ -314,7 +324,7 @@ lectures = []
- `mzl` reprend exactement les trois chiffres du nom de fichier ;
- `lectures` contient les lectures translittérées.
Le nom `mzl-XXX.md` est contrôlé même lorsque la fiche est encore en brouillon. Avant publication, le titre, le glyphe et le numéro MZL doivent être renseignés, et le numéro doit correspondre au nom du fichier.
Le nom `mzl-XXX.md` est contrôlé même lorsque la fiche est en brouillon. Avant publication, le titre, le glyphe et le numéro MZL doivent être renseignés, et le numéro doit correspondre au nom du fichier.
Le corps peut accueillir, selon le besoin :
@@ -412,7 +422,7 @@ Ils sont ajoutés lorsqu’ils apportent un contexte réel : occurrence dans un
## Ce que contrôle le validateur
Le validateur vérifie pour tous les fichiers Markdown :
Pour tous les fichiers Markdown, le validateur vérifie :
- l’encodage UTF-8 ;
- la normalisation Unicode NFC du contenu et du chemin ;
@@ -423,7 +433,7 @@ Pour les fichiers `_index.md`, il exige un titre non vide.
Pour les autres pages, `draft` doit être un booléen. Les brouillons ne sont pas soumis aux contrôles de complétude, à l’exception du nom des fiches de signes.
Pour toute page publiée, il exige un titre non vide. Lorsque la page appartient à une section, `date` doit être un horodatage TOML avec fuseau horaire. Si `updated` est renseigné, il doit respecter le même format. Les pages permanentes placées directement dans `src/content/`, comme la bibliographie et les mentions légales, n’ont pas besoin de date.
Pour toute page publiée, il exige un titre non vide. Lorsque la page appartient à une section, `date` doit être un horodatage TOML avec fuseau horaire. Si `updated` est actif, il doit respecter le même format. Les pages permanentes placées directement dans `src/content/`, comme la bibliographie et les mentions légales, n’ont pas besoin de date.
Pour une fiche de vocabulaire publiée, il contrôle en plus :
@@ -441,6 +451,7 @@ Zola reste responsable de la construction, des liens internes, des taxonomies et
## 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 ;
README.md
+14 -95
View File
@@ -1,24 +1,20 @@
# Les Carnets d’Akkadien
**Les Carnets d’Akkadien** est un site personnel consacré à l’apprentissage de l’akkadien et de l’écriture cunéiforme. Il réunit des fiches de vocabulaire, des signes, des notes de grammaire, des textes étudiés et des articles de parcours.
**Les Carnets d’Akkadien** est un site personnel consacré à l’apprentissage de l’akkadien et de l’écriture cunéiforme. Il rassemble des fiches de vocabulaire et de signes, des notes de grammaire, des textes étudiés et des articles de parcours.
Site public : <https://lescarnetsdakkadien.netig.net>
Le site est construit avec [Zola](https://www.getzola.org/) à partir de fichiers Markdown. Il ne nécessite ni base de données ni interface d’administration : les contenus restent lisibles et modifiables comme de simples fichiers texte.
## Contenu du site
## Sections du site
| Section | Contenu | Classement complémentaire |
|---|---|---|
| `articles` | articles sur l’apprentissage et le projet | — |
| `grammaire` | notes consacrées aux notions grammaticales | thèmes |
| `signes` | signes cunéiformes classés par numéro MZL | lectures |
| `textes` | translittérations, traductions et commentaires | genres |
| `vocabulaire` | fiches lexicales adaptées à leur nature grammaticale | natures |
- **Signes** : signes cunéiformes classés par numéro MZL et par lecture ;
- **Vocabulaire** : fiches adaptées à la nature grammaticale des mots ;
- **Grammaire** : notes organisées par thème ;
- **Textes** : translittérations, traductions et commentaires classés par genre ;
- **Articles** : billets consacrés à l’apprentissage et au projet.
La page d’accueil présente le dernier article et les trois fiches les plus récemment publiées ou mises à jour parmi les signes, le vocabulaire, la grammaire et les textes. Des flux Atom et RSS sont également générés.
Les conventions de rédaction et les champs disponibles sont décrits dans le [guide de rédaction](GUIDE_REDACTION.md).
La page d’accueil présente le dernier article et les trois fiches les plus récemment publiées ou mises à jour. Des flux Atom et RSS sont également générés.
## Prérequis
@@ -49,7 +45,7 @@ Vérifier la construction Zola, brouillons compris :
zola --root src check --drafts --skip-external-links
```
`--skip-external-links` évite de dépendre du réseau. Retirer cette option pour contrôler aussi les liens externes.
`--skip-external-links` évite de dépendre du réseau. Retirer cette option pour vérifier également les liens externes.
Lancer le serveur de développement :
@@ -71,83 +67,11 @@ zola --root src build
Le résultat est écrit dans `src/public/`, répertoire ignoré par Git.
## Créer un contenu
## Rédaction des contenus
Le générateur crée un brouillon horodaté avec le front matter adapté à la section :
Les contenus sont rédigés en Markdown dans `src/content/`. Des scripts permettent de créer les squelettes, d’horodater les modifications substantielles et de vérifier les fiches avant publication.
```sh
./scripts/new-content.py vocabulaire šarrum --nature nom
```
Exemples :
```sh
./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
./scripts/new-content.py vocabulaire --nature particule -- -ma
```
Chaque fichier est créé avec :
- une date au format TOML dans le fuseau `Europe/Paris` ;
- un repère commenté `# updated = YYYY-MM-DDTHH:MM:SS+HH:MM` pour les mises à jour substantielles ;
- `draft = true` ;
- tous les champs prévus par son modèle ;
- des chaînes vides ou des listes vides pour les données à compléter.
Le générateur refuse d’écraser un fichier existant. Son aide complète est disponible avec :
```sh
./scripts/new-content.py --help
```
## Horodater une mise à jour
Après une modification substantielle, renseigner automatiquement `updated` avec l’heure courante de `Europe/Paris` :
```sh
./scripts/update-content.py src/content/vocabulaire/bītum.md
```
Ce chemin se complète directement avec la touche Tab du shell. La forme abrégée, relative à `src/content/`, est également acceptée :
```sh
./scripts/update-content.py vocabulaire/bītum.md
```
Le script remplace l’unique ligne `updated`, qu’elle soit commentée ou active. La fiche doit donc toujours conserver cette ligne.
## Publier un contenu
Le cycle de rédaction recommandé est simple :
1. créer le brouillon avec `new-content.py` ;
2. compléter le front matter et le corps Markdown ;
3. vérifier que `date` correspond à la date de publication souhaitée ;
4. remplacer `draft = true` par `draft = false` ;
5. lancer le validateur et Zola.
```sh
./scripts/check-content.py
zola --root src check --drafts --skip-external-links
```
Le validateur contrôle les invariants qui doivent rester vrais indépendamment du rendu :
- encodage UTF-8 et normalisation Unicode NFC ;
- front matter TOML valide ;
- section connue et statut de brouillon valide ;
- titre des index et des pages publiées ;
- horodatage de publication des pages publiées dans une section ;
- horodatage de `updated` lorsqu’il est renseigné ;
- nom et numéro MZL des fiches de signes ;
- nature, champs et types des fiches de vocabulaire publiées.
Les brouillons peuvent rester incomplets. Le nom `mzl-XXX.md` d’une fiche de signe reste toutefois contrôlé même en brouillon, car il détermine son identité et son URL future.
Une erreur renvoie un code de sortie non nul et bloque également la construction Docker.
Les conventions éditoriales, les commandes et les modèles de chaque type de fiche sont décrits dans le [guide de rédaction](GUIDE_REDACTION.md).
## Organisation du dépôt
@@ -177,16 +101,11 @@ Une erreur renvoie un code de sortie non nul et bloque également la constructio
- `src/sass/main.scss` contient les styles ;
- `src/static/` contient les ressources servies telles quelles ;
- `src/zola.toml` contient la configuration de Zola ;
- `scripts/new-content.py` crée les brouillons ;
- `scripts/update-content.py` horodate les modifications substantielles ;
- `scripts/check-content.py` valide les contenus ;
- `scripts/_schema.py` contient les définitions communes au générateur et au validateur.
Les chemins et les taxonomies utilisent la stratégie de slugification `safe` de Zola. Les diacritiques sont donc conservés : des lectures comme `tim` et `ṭim` restent distinctes.
- `scripts/` contient les outils de création, de mise à jour et de validation des contenus.
## Déploiement avec Docker Compose
L’image est construite en trois étapes : validation des contenus, construction avec Zola 0.22.1, puis service du site statique.
L’image est construite en trois étapes : validation des contenus, construction avec Zola 0.22.1, puis service des seuls fichiers statiques.
Vérifier la configuration :