lescarnetsdakkadien.netig.net/README.md

# 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 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 généré avec **Zola 0.23.1** et **Tera 2** à partir de fichiers Markdown. Il est entièrement statique : aucune base de données, aucune interface d’administration et aucune exécution côté serveur ne sont nécessaires.

## Contenu

- **Signes** : signes cunéiformes classés par numéro MZL et par lecture ;
- **Vocabulaire** : fiches adaptées à la nature grammaticale des mots ;
- **Grammaire** : notes regroupé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. Un flux Atom est disponible à l’adresse `/atom.xml`.

## Prérequis

Pour le développement local :

- Python 3.11 ou ultérieur ;
- Zola 0.23.1 ;
- Git, si le dépôt est versionné avec Git.

Pour le déploiement décrit ici :

- Docker Engine et Docker Compose ;
- Caddy 2 sur l’hôte public.

Toutes les commandes suivantes sont exécutées depuis la racine du dépôt.

## Développement local

Valider la structure des fiches :

```sh
./scripts/check-content.py
```

Vérifier le chargement du site et ses liens, brouillons compris :

```sh
zola --root src check --drafts
```

Sans accès réseau, les liens externes peuvent être ignorés :

```sh
zola --root src check --drafts --skip-external-links
```

Rendre le site avec les brouillons afin de tester tous les templates :

```sh
zola --root src build --drafts
```

Construire ensuite la version publique, sans les brouillons :

```sh
zola --root src build
```

Les fichiers générés sont écrits dans `src/public/`, répertoire ignoré par Git.

Lancer le serveur de développement :

```sh
zola --root src serve
```

Afficher également les brouillons :

```sh
zola --root src serve --drafts
```

## Rédaction

Les contenus sont stockés dans `src/content/`. Trois commandes accompagnent leur rédaction :

- `new-content.py` crée un brouillon complet pour une section donnée ;
- `update-content.py` actualise son horodatage `updated` ;
- `check-content.py` vérifie la présence et le type des champs prévus.

Le module `_schema.py` centralise les modèles utilisés par le générateur et le validateur ; il n’est pas exécuté directement.

Les commandes, conventions et modèles de front matter sont détaillés dans le [guide de rédaction](GUIDE_REDACTION.md).

## Architecture

```text
.
├── Caddyfile.example
├── Dockerfile
├── compose.yml
├── README.md
├── GUIDE_REDACTION.md
├── LICENSE-CODE
├── LICENSE-CONTENT
├── scripts/
└── src/
    ├── content/
    ├── sass/main.scss
    ├── static/
    ├── templates/
    │   ├── components.html
    │   ├── partials/
    │   └── *.html
    └── zola.toml
```

- `src/content/` contient les sources Markdown ;
- `src/templates/components.html` contient les composants Tera 2 paramétrés ;
- `src/templates/partials/` contient les fragments utilisant le contexte courant ;
- `src/templates/sitemap.xml` retire du sitemap les taxonomies sans contenu publié ;
- `src/sass/main.scss` définit l’apparence, le responsive et l’impression ;
- Zola génère `giallo.css` à partir du thème `github-light` pour la coloration syntaxique par classes ;
- `src/static/` contient les images, la police et le favicon servis tels quels ;
- `src/zola.toml` contient la configuration générale, les taxonomies et le flux Atom.

`giallo.css` et `main.css` sont des fichiers générés dans `src/public/` : ils ne doivent pas être ajoutés manuellement à `src/static/`.

## Déploiement avec Docker Compose

L’image est construite en trois étapes :

1. validation des fiches avec Python ;
2. génération du site avec Zola 0.23.1 ;
3. copie des seuls fichiers publics dans un serveur HTTP statique.

Vérifier puis démarrer le service :

```sh
docker compose config
docker compose up -d --build
```

Le conteneur est exposé uniquement sur l’interface locale de l’hôte :

```text
http://127.0.0.1:8002
```

Pour mettre à jour le déploiement :

```sh
git pull --ff-only
docker compose up -d --build
```

Pour l’arrêter :

```sh
docker compose down
```

## Proxy inverse Caddy

Caddy prend en charge le domaine public, HTTPS, les en-têtes de sécurité et la politique de cache. Le serveur HTTP interne désactive ses propres en-têtes de cache et de sécurité afin d’éviter deux configurations concurrentes.

[`Caddyfile.example`](Caddyfile.example) fournit le bloc correspondant au port publié par `compose.yml`. Il applique :

- `Cache-Control: no-cache` aux documents ;
- un cache navigateur d’une journée aux feuilles de style, images et polices ;
- une CSP compatible avec les ressources locales du site ;
- HSTS, `Referrer-Policy`, `X-Content-Type-Options` et `X-Frame-Options`.

Le fichier peut être importé au niveau principal du Caddyfile de l’hôte ou servir de modèle pour un bloc existant. Sa syntaxe peut être contrôlée avec :

```sh
caddy validate --config Caddyfile.example --adapter caddyfile
```

## Flux Atom

Le flux est activé dans `src/zola.toml` :

```toml
generate_feeds = true
feed_filenames = ["atom.xml"]
```

Le template de base affiche automatiquement la balise de découverte et le lien du pied de page lorsque cette configuration est active.

## 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.