238 lines
7.1 KiB
Markdown
238 lines
7.1 KiB
Markdown
# 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.
|
||
|
||
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
|
||
|
||
| 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 |
|
||
|
||
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).
|
||
|
||
## Prérequis
|
||
|
||
Pour travailler directement sur le projet :
|
||
|
||
- Python 3.11 ou ultérieur ;
|
||
- Zola 0.22.1 ;
|
||
- Git, si le dépôt est versionné avec Git.
|
||
|
||
Pour le déploiement conteneurisé :
|
||
|
||
- Docker Engine ;
|
||
- Docker Compose.
|
||
|
||
Toutes les commandes ci-dessous sont exécutées depuis la racine du dépôt.
|
||
|
||
## Développement local
|
||
|
||
Valider les contenus :
|
||
|
||
```sh
|
||
./scripts/check-content.py
|
||
```
|
||
|
||
Vérifier la construction Zola, brouillons compris :
|
||
|
||
```sh
|
||
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.
|
||
|
||
Lancer le serveur de développement :
|
||
|
||
```sh
|
||
zola --root src serve
|
||
```
|
||
|
||
Afficher également les brouillons :
|
||
|
||
```sh
|
||
zola --root src serve --drafts
|
||
```
|
||
|
||
Construire le site statique :
|
||
|
||
```sh
|
||
zola --root src build
|
||
```
|
||
|
||
Le résultat est écrit dans `src/public/`, répertoire ignoré par Git.
|
||
|
||
## Créer un contenu
|
||
|
||
Le générateur crée un brouillon horodaté avec le front matter adapté à la section :
|
||
|
||
```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 active le repère commenté, remplace l’horodatage existant ou insère `updated` après `date` lorsqu’il est absent.
|
||
|
||
## 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.
|
||
|
||
## Organisation du dépôt
|
||
|
||
```text
|
||
.
|
||
├── Dockerfile
|
||
├── compose.yml
|
||
├── README.md
|
||
├── GUIDE_REDACTION.md
|
||
├── LICENSE-CODE
|
||
├── LICENSE-CONTENT
|
||
├── scripts
|
||
│ ├── _schema.py
|
||
│ ├── check-content.py
|
||
│ ├── new-content.py
|
||
│ └── update-content.py
|
||
└── src
|
||
├── content
|
||
├── sass
|
||
├── static
|
||
├── templates
|
||
└── zola.toml
|
||
```
|
||
|
||
- `src/content/` contient les pages Markdown ;
|
||
- `src/templates/` contient les templates Tera ;
|
||
- `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 aux outils de gestion des contenus.
|
||
|
||
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.
|
||
|
||
## 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.
|
||
|
||
Vérifier la configuration :
|
||
|
||
```sh
|
||
docker compose config
|
||
```
|
||
|
||
Construire et lancer le service :
|
||
|
||
```sh
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Consulter son état et ses journaux :
|
||
|
||
```sh
|
||
docker compose ps
|
||
docker compose logs --tail=100 zola
|
||
```
|
||
|
||
Le service écoute uniquement sur l’interface locale de l’hôte :
|
||
|
||
```text
|
||
http://127.0.0.1:8002
|
||
```
|
||
|
||
Le domaine public et le certificat TLS sont pris en charge par un proxy inverse placé devant le conteneur.
|
||
|
||
Mettre à jour le déploiement :
|
||
|
||
```sh
|
||
git pull --ff-only
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Arrêter le service :
|
||
|
||
```sh
|
||
docker compose down
|
||
```
|
||
|
||
## Licences
|
||
|
||
Le code propre au projet est distribué sous licence MIT ; voir [`LICENSE-CODE`](LICENSE-CODE).
|
||
|
||
Sauf mention contraire, les contenus originaux de `src/content/` sont publiés sous licence CC BY-SA 4.0 ; voir [`LICENSE-CONTENT`](LICENSE-CONTENT).
|
||
|
||
Les polices, photographies et autres ressources tierces restent soumises à leurs propres droits et licences.
|