218 lines
6.3 KiB
Markdown
218 lines
6.3 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 datées les plus récentes 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` ;
|
||
- `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
|
||
```
|
||
|
||
## 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 ;
|
||
- date des pages publiées dans une section ;
|
||
- 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
|
||
└── 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/check-content.py` valide les contenus ;
|
||
- `scripts/_schema.py` contient les définitions communes aux deux scripts.
|
||
|
||
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.
|