Meilleure répartition de la documentation
This commit is contained in:
julien committed
1 parent
81616e11e3
commit
cc1b03b78e
2 files changed
+111
-181
No files matched your search
@@ -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 :
|
||||
|
||||
|
||||
Reference in new issue
Block a user