| old-hugo-site/themes/distorsion/osprey | ||
| site | ||
| .gitignore | ||
| .woodpecker.yml | ||
| README.md | ||
Le site web de la distorsion !
TODO
- Ecrire le contenu de la page présentation.
- Documenter l'édition du site à partir de l'interface web du dépot git. Comment rajouter/enlever des évènements à venir ? Comment ajouter un billet de blog ? Comment ajouter une feuille de style ?
Site actuel
Le site est super basique : c'est juste des fichiers statiques html, css et js servis depuis un bucket S3, hébergé chez les camarades de deuxfleurs.
Edition
On choisit volontairement de s'imposer des contraintes techniques assez fortes pour que le site reste le plus simple possible, et puisse servir de support pour comprendre les technologies à la base du Web. On veille collectivement à cette simplicité, ce qui implique le mode de fonctionnement suivant pour les éditions du site :
- Pour les petites éditions de contenu, typiquement mettre à jour la liste des
évènement à venir : push dans la branche
main. - Pour tout le reste à priori, comme éditer la structure du site (header, footer, CSS) ou ajouter des billets de blog, on fait les modifications dans une branche séparée, et on ouvre une pull request.
Choix techniques
On essaye de documenter ici les choix techniques qui ont fait l'objet de débats, et qui sont peut être pas évidents.
2024/10/25: Gestion du contenu qui se répète
Les contenus qui se répète sont principalement les éléments <head>,
<header> et <footer> qui se retrouvent sur toutes les pages HTML. On a considéré les possibilités suivantes :
- Utiliser un générateur de site simple.
- Utiliser du Server Side Include (SSI) pour charger le serveur web d'ajouter le contenu qui se répète.
- Ecrire un petit script bash qui ajoute le contenu commun avec des simples
catetsed. - Ecrire un petit script JavaScript qui ajoute le contenu commun dynamiquement à toutes les pages.
Ces solutions ont toutes le désavantage de rendre le site plus "opaque". Les fichiers que l'on voit dans le dépot ne sont plus directement ceux qui sont servis au navigateur, ce qui ajoute une barrière supplémentaire à une personne qui essaye de comprendre le site. Les deux dernières sont une pente glissante vers la réécriture d'un générateur de site maison (ce qui n'est pas forcément mal). Le SSI n'est pas vraiment une option tant que le site est hébergé chez DeuxFleurs, car leur infrastructure ne le supporte pas.
On a donc décidé de répéter le contenu dans tous les fichiers. Si on écrit bien les parties redondantes, elles ne devraient pas être modifiées très souvent. Quand c'est le cas, on peut facilement comprendre la tâche à faire, et éventuellement écrire un petit script bash simple pour réaliser cette tâche. C'est l'occasion d'apprendre quelque chose ensemble.
Evidemment, c'est pas idéal comme situation. Y'a un risque que les parties qui sont censées être communes finissent par se désynchroniser. On verra bien à l'usage.
2024/10/25: Flex
Pour centrer le contenu sur toutes les pages dans le css par défaut, on a
décidé de transformer le <body> en un conteneur flex. Flex c'est un peu
compliqué (nous même on comprend pas bien comment ça marche) mais ça permet que
tous les nouveaux éléments ajoutés dans la page comme enfant du <body> soient
centrés, sans qu'il ne faille ajouter margin: auto dessus à chaque fois.
Tester le site en local
Pour tester le site en local, il faut un serveur web local. L'une des options les plus simples qui ne demande pas de configuration est d'utiliser celui qui vient avec Python. Depuis la racine du site, lancer
python -m http.server
Puis pointer un navigateur vers http://localhost:8000.
Comme on utilise des chemins absolus pour les références entre les fichiers du site, simplement ouvrir les fichiers html avec le navigateur va casser des références (aux fichiers css par exemple, ou des liens). On a besoin de passer par un serveur web pour que le site ait une racine bien définie.
Déploiement
Automatique
Si c'est un bon jour, toutes les modifications dans la branche main sont
automatiquement poussées dans le bucket S3 par Woodpecker.
Il faut une clef secrète pour pouvoir accéder au bucket. Avec Woodpecker, on a configuré un "secret" qui contient cette clef, donc pas besoin de la connaître pour mettre à jour le site.
A la main
Si Woodpecker marche pas pour une raison où une autre, on peut copier les sources à jour à la main dans le bucket S3. Pour ça, il faut connaître la clef d'accès au bucket, et son identifiant. Si besoin, on peut les partager.
Il existe plein de clients S3. Avec s5cmd par exemple, ça donne ça :
export AWS_ACCESS_KEY_ID=<key ID>
export AWS_SECRET_ACCESS_KEY=<secret key>
export AWS_DEFAULT_REGION='garage'
export AWS_ENDPOINT='https://garage.deuxfleurs.fr'
s5cmd --endpoint-url $AWS_ENDPOINT sync --delete site/ s3://distorsion.interhacker.space/
Ancien site
Avant, on avait un site static généré avec Hugo. Les sources sont archivées dans l'historique de git.