diff --git a/README.md b/README.md index f050adf..71a187c 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,7 @@ ## 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 ? +- Héberger nos propre runners ? ## Site actuel @@ -15,19 +12,107 @@ 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](https://deuxfleurs.fr). -## 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 comprendre les technologies à la base du Web, et on essaye de veiller +collectivement à cette simplicité. + +## Edition + +Pour les éditions du site, on a le fonctionnement suivant : - Pour les petites éditions de contenu, typiquement mettre à jour la liste des - évènement à venir : push dans la branche `main`. + évènement à venir : on édite directement (on push dans la branche `main`). +- Pour ajouter des styles dans le menu de changement de styles, on les ajoute + directement aussi. - 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. + footer, CSS) ou ajouter des billets de blog, on demande aux autres leur avis, + sur les canaux de communication ou en vrai, et si ça va à tout le monde on + édite. Si on sait utiliser git, on peut faire les modifications dans une + branche séparée, et ouvrir une pull request. + +Il ne faut surtout pas hésiter à demander de l'aide si ça te semble trop +compliqué d'éditer le site ! + +C'est possible de faire les éditions directes dans l'interface web. Par +example, pour rajouter un évènement, on peut : aller dans `site`, cliquer sur +`index.html` (la page principale du site), cliquer sur le crayon dans la barre +au dessus du contenu du fichier pour éditer, et rajouter un pragraphe pour +l'évènement. Actuellement, ce serait à la ligne 31 du fichier, et on pourrait +ajouter : + +``` +

Date, heure de l'évènement et description de l'évènement !

+``` + +Et enfin, en bas de la page, ajouter une petite description du changement et +cliquer sur "Réviser" / "Commit". + +Pour ajouter un style, on peut ajouter le fichier css dans le dossier +`site/css`, puis modifier le fichier `styleswitcher.js` dans `site/js` pour +ajouter son style dans le dictionnaire en haut du fichier, en ajoutant une +ligne : + +``` +"Nom du style": "/css/fichier-css.css", +``` + +Pour les articles de blog, on peut créer un nouveau fichier, y copier-coller le +contenu d'un des articles du dossier `site/blog`, supprimer tout ce qu'il y a +entre
et
, et rajouter notre contenu à la place. Après, on +demande aux autres ce qu'iels pensent de l'article, et si on décide de le +publier, on peut ajouter le nouveau fichier dans le dossier blog, puis modifer +le fichier `blog.html` pour y ajouter le nouvel article. + +Pour apprendre à faire des sites web, le site [MDN de +mozilla](https://developer.mozilla.org/fr/docs/Learn) est une bonne ressource. + +## 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. Dans un terminal, depuis la racine du site, lançer + +``` +python -m http.server +``` + +Puis pointer un navigateur web 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= +export AWS_SECRET_ACCESS_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/ +``` + +La clef et son ID ne sont pas stockées ici. Si besoin, ces secrets peuvent être +partagés. ## Choix techniques @@ -37,7 +122,8 @@ 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 ``, -`
` et `