Documente l'édition du site
This commit is contained in:
parent
a599124c69
commit
386b535321
1 changed files with 99 additions and 57 deletions
156
README.md
156
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 :
|
||||
|
||||
```
|
||||
<p><strong>Date, heure de l'évènement</strong> et description de l'évènement !</p>
|
||||
```
|
||||
|
||||
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 <main> et </main>, 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=<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/
|
||||
```
|
||||
|
||||
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 `<head>`,
|
||||
`<header>` et `<footer>` qui se retrouvent sur toutes les pages HTML. On a considéré les possibilités suivantes :
|
||||
`<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
|
||||
|
|
@ -73,50 +159,6 @@ compliqué (nous même on comprend pas bien comment ça marche) mais ça permet
|
|||
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](https://gohugo.io). Les
|
||||
|
|
|
|||
Loading…
Reference in a new issue