aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorQuentin Dufour <quentin@deuxfleurs.fr>2020-05-28 15:00:23 +0200
committerQuentin Dufour <quentin@deuxfleurs.fr>2020-05-28 15:00:23 +0200
commit6821c94d48308766cba30e262c0b092e644d5d32 (patch)
treeef044325481e647b4bccf8e6564422fc9de17e61 /README.md
parenta171273a015f5c3da68d5db9b4159ffb6b98fd79 (diff)
downloadsite-6821c94d48308766cba30e262c0b092e644d5d32.tar.gz
site-6821c94d48308766cba30e262c0b092e644d5d32.zip
Doc pour le site web
Diffstat (limited to 'README.md')
-rw-r--r--README.md66
1 files changed, 61 insertions, 5 deletions
diff --git a/README.md b/README.md
index b42b166..758a846 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,69 @@
# site
-Sources of the [deuxfleurs.fr](https://deuxfleurs.fr/) website (in french).
+Ce dépôt git contient les sources pour le site [deuxfleurs.fr](https://deuxfleurs.fr/).
+C'est ici que vous pourrez apporter des modifications au site.
-## Deployment
+## Comment ajouter du contenu ?
-Automagically deployed on commit to master!
+Prérequis :
+ - Un compte sur cette instance gitea.
+ - Le logiciel git d'installé. [téléchager](https://git-scm.com/downloads).
-## Building
+Pour commencer, assurez-vous d'être connecté.
+Ensuite cliquez sur le bouton "Bifurcation" en haut à droite (*fork* en anglais).
+Finalement, vous pourrez cloner votre dépôt en local :
```
-./.webpull
+git clone https://git.deuxfleurs.fr/<votre nom d'utilisateur>/site.git
+```
+
+Pour ajouter du contenu, vous pouvez tout simplement ajouter un fichier dans le dossier `src`.
+Par exemple, le fichier `src/Association/Statuts.md` se retrouve à l'adresse `https://deuxfleurs.fr/Association/Statuts.html`.
+
+Deux formats de fichiers différents sont supportés pour l'instant :
+
+ - `.md` pour Markdown. [documentation](https://fr.wikipedia.org/wiki/Markdown). Rapide à apprendre, il est très pratique pour rajouter du contenu sans se poser la question de l'apparence.
+ - `.pug` pour Pug. [documentation](https://pugjs.org). PugJS est une syntaxe différente pour représenter du HTML. Elle offre donc toute la souplesse de ce dernier et s'adapte plus à des mises en page complexe.
+
+Si vous ne savez pas par où commencer, choisissez markdown !
+N'hésitez pas à vous inspirer des fichiers existants.
+
+Une fois vos modifications terminées, vous pouvez commit et push :
+
+```
+git add src/Association/MonFichier.md
+git commit -a
+git push
```
+
+Ensuite, vous pouvez créer une demande d'ajout (*pull request* ou *merge request* en anglais) depuis cette adresse (ou en cliquant sur l'onglet éponyme) : https://git.deuxfleurs.fr/Deuxfleurs/site/pulls
+
+## Comment prévisualiser mes modifications ?
+
+Prérequis :
+ - nodejs et npm d'installé. [télécharger](https://nodejs.org/en/download/)
+
+Vous pourriez vouloir vérifier que vos modifications rendent bien avant de faire votre demande d'ajout.
+Pour cela, nous utilisons un script de notre cru nommé `render.js`. Il convertit le dossier `src/` vers un site web contenu dans le dossier `static/` et peut, optionnellement, servir de serveur web.
+
+La façon la plus simple de prévisualiser vos modifications est donc de :
+
+```bash
+npm install # installer les dépendances
+LISTEN=3000 node render.js # effectuer le rendu puis démarrer un serveur web sur le port 3000
+```
+
+Votre aperçu est alors disponible à cette URL : http://127.0.0.1:3000
+
+À chaque modification, vous pouvez arrêter la dernière commande (CTRL+C) et la relancer pour forcer le rendu.
+
+## Comment le site est mis à jour depuis ce dépôt ?
+
+Tout est réalisé automatiquent, aucune intervention humaine n'est nécessaire.
+
+Derrière les coulisses, une fois que votre demande d'ajout acceptée, elle arrive sur la branche `master` de ce dépôt.
+Cette opération déclenche automatiquement [un webhook gitea](https://docs.gitea.io/en-us/webhooks/) qui va alors effectuer une requete HTTP sur l'URL suivante : `https://deuxfleurs.fr/update?token=<redacted>`.
+Le serveur sait alors qu'il doit rafraichir le site web.
+Cette fonctionnalité est fournie par un petit outil qui s'appelle [webpull](https://git.deuxfleurs.fr/Deuxfleurs/deuxfleurs.fr/src/branch/master/docker/webpull).
+Ce dernier exécute alors deux commandes : `git pull` puis `./.webpull`.
+`.webpull` est en réalité un script bash contenu dans ce dépôt à la racine, dont vous pouvez inspecter le contenu.