Le site web de MixTeen

Ce projet permet de gérer le site web de MixTeen.

Commme nous allons le voir plus bas le site est généré statiquement et tout est génére à l’installation. Installation en local pour développer ou ajouter du contenu, mais aussi lorsque le site est installé sur le serveur de production. Le but est vraiment de pouvoir bénéficier des mêmes outils quelque soit l’environnement.

Pruduction:

• URL: https://mixteen.org/

• branche git: prod

Pré-production:

• URL: https://mixteen-staging.cleverapps.io/index.html

• branche git: master

Contribuer au site

La partie technique est détaillée plus bas dans le document, mais pour l’écriture d’article en résumé il faut: - sur une branche git dédiée - créer un fichier texte adoc dans src/blog/<année> - ajouter la ou les images dans images/blog/[annee] - faire une Pull Request qui cible master - le build devrait se lancer et générer le site dans archive-dist-folder

Level 1 : ajouter un article

Pour chaque événement on rajoute un article dans le répertoire blog. Les différents posts sont classés par année. Afin d’illustrer un article c’est bien d’utiliser une image dans la banque d’images que l’on peut trouver sous flickr ou ailleurs. Comme ça dans la liste des posts de notre blog on aura aussi bien une image et du texte

Pour rappel les articles de blog apparaissent

• sur la home (les 2 derniers)

• la page blog la liste des 20 derniers

• la page archive où on retrouvera l’intégralité

Ressources

Chaque article doit au moins avoir:

• une image de 1500 pixels par 764 (ou 640 x 326). Dans Gimp c’est simple d’aller changer les dimensions (Menu Image > Canvas Size ou Menu Image > Resize image

• un titre unique (important pour les moteurs de recherche)

• une phrase d’intro qui sera reprise dans le descriptif des articles de blogs

• un contenu avec potentiellement d’autres images

Les images des articles, pour plus de clarté, doivent être mises dans le répertoire images/blog/[annee]

Nom fichier source article

Pour débuter vous pouvez copier un article existant.

Il est important de ne pas avoir de caractères spéciaux dans le nom du fichier .adoc.

Remplacez les espaces par des _

Ce nom est important car la page HTML aura exactement le même nom. Soyez concis et clair

Rédaction

Les articles sont rédigés en Asciidoctor. La doc est assez complète https://asciidoctor.org/docs/user-manual/

:doctitle: RMML 2017
:description:  MixTeen est aux rencontres mondiales du logiciel libre à Saint Etienne le mercredi 5 juillet 2017
:keywords: RMLL
:author: Guillaume EHRET - MixTeen
:revdate: 2017-07-05
:category: Web
:teaser: MixTeen est aux rencontres mondiales du logiciel libre à Saint Etienne le mercredi 5 juillet 2017 avec un atelier construire son propre ordinateur
:imgteaser: ../../img/blog/2017/rmll_00.png


== Rencontres mondiales du logiciel libre à Saint Etienne le mercredi 5 juillet

Ceci est un exemple d'article et on peut écrire en ascii doctor

Le générateur du site va exploiter les premières lignes du fichier

• doctitle ⇒ utilisé pour la balise <title> dans le head de la page HTML

• description ⇒ utilisé pour la balise <meta name="description"> dans le head de la page HTML

• keywords ⇒ utilisé pour la balise <meta name="keywords"> dans le head de la page HTML

• author ⇒ utilisé sur le détail d’un article

• revdate ⇒ au format anglais 2017-07-05, cette date est utilisée pour trier les articles

• category ⇒ donne des infos sur le détail d’un article

• teaser ⇒ c’est le texte que l’on retrouve pour résumer l’article

• imgteaser ⇒ un lien relatif vers l’image utilisée. Par exemple ../../img/blog/2017/rmll_00.png

Level 2 : page HTML

Pour ajouter une page statique au site, il est possible de le faire en ajoutant un fichier dans le répertoire HTML. Vous ne vous souciez que du contenu. Tout le reste est automatiquement ajouté lors de la génération du site

Par contre comme nous avons besoin de générer un titre, une description…​ A chaque fos que vous ajoutez une page dans ce répertoire vous devez mettre à jour le fichier src/metadata/html.json.

Par exemple

{
  "404.html" : {
    "keywords": "MixTeen est une association créée pour promouvoir le code et l'informatique auprès des enfants et des ados",
    "title": "MixTeen 404",
    "description" : "Page non trouvée sur le serveur",
    "priority": -1
  },

}

La clé est le nom du fichier html. On trouve les propriétés suivantes

• title ⇒ utilisé pour la balise <title> dans le head de la page HTML

• description ⇒ utilisé pour la balise <meta name="description"> dans le head de la page HTML

• keywords ⇒ utilisé pour la balise <meta name="keywords"> dans le head de la page HTML

• priority ⇒ utilisé dans le fichier sitemap.xml pour la pertinence

Si cette page doit être ajoutée au menu, tu peux modifier le fichier src/template/_page_header.handlebars.

Si tu oublies de référencer la page dans le fichier metadata, tu auras une erreur à l’installation du site

Level 3 : template Handlebars

Handlebars est utilisé pour éviter de faire de la duplication de code entre les pages. Normalement le seul template que l’on a vraiment besoind e changer est le template index.handlebars qui contient le contenu de la home. C’est un template et pas une page HTML car on insère à l’intérieur les deux derniers articles de blog.

Les sous templates sont

• _html_footer.handlebars : pied HTML (fichiers JavaScript)

• _html_header.handlebars : entête HTML (metadata, fichier CSS…​)

• _page_footer.handlebars : pied de page (lien, copyright)

• _page_header.handlebars : menu

Les autres templates sont

• blog.handlebars : le template utilisé pour le détail d’un article de blog

• blog_archive.handlebars : archive avec tous les blogs depuis le début

• blog_list.handlebars : la page blog avec les 20 derniers articles

• index.handlebars : la page index avec les 2 derniers articles

• site.handlebars : la page site qui est utilisé pour générer les pages qui sont dans le réertoire HTML

Deploiements en préproduction et production

• La branche master est automatiquement deployée en préprod

• La branche prod est automatiquement deployée en produdction

Pour deployer il suffit de: * vérifier que la version sur master est ok sur https://mixteen-staging.cleverapps.io/index.html * faire unr Pull Request de master vers prod * faire vérifier à un autre humain 👀 qui valide la PR * merger

D’un point de vue technique

La version courte

• Node = 14 A faire: pour l’instant le build ne passe pas en Node 16.

Si vous utilisez asdf vous pouvez installer la version de nodejs avec (cf .tool-versions):

---
asdf plugin add nodejs
asdf install
---

Puis:

---
npm install -g yarn
npm install -g gulp-cli
yarn install
yarn start
---

Compatibilité navigateur

Le site n’est compatible que sur les navigateurs dits "modernes" (pouvant exécuter du JavaScript ES > 6). Vous pouvez donc utiliser les navigateurs suivant

• Chrome

• Edge

• Firefox

• Safari

• Edge voir Internet Explorer >= 11

Configurer ton poste de développement

Ce projet est Open Source et toutes les personnes motivées sont les bienvenues pour nous aider à faire évoluer notre site web.

D’un point de vue technique tu as besoin pour lancer le site en local

• D’une version de Node JS > 10.0. Tu peux aller sur le site pour installer Node sur ta machine. Le site ne fonctionne pas directement avec Node mais nous utilisons l’écosystème JavaScript pour le générer.

• Lors de l’installation nous allons télécharger des dépendances Node et pour celà nous utilisons le gestionnaire de paquets Yarn. Si yarn n’est pas installé tu peux lancer dans un terminal la commande npm install -g yarn (npm est automatiquement installé en même temps que Node)

• Le cycle de vie de l’application est lui géré par l’application Gulp. Si gulp n’est pas installé tu peux lancer dans un terminal la commande npm install -g gulp-cli

• Le site utilise FireBase pour la gestion des commentaires. Notre compte est https://mixteen-d85dc.firebaseio.com. Pour commencer à développer tu n’as rien besoin de paramétrer sur ton poste

Installer le site en local

Une fois que tous les outils décrits dans la partie précédente sont installés tu peux lancer les commandes suivantes

Initialiser le projet et charger les librairies utilisées pour le développement

yarn install

Lancer le site en local

yarn start

Cette commande Gulp effectue différentes tâches que tu peux lancer individuellement si tu veux tester une phase particulière de la construction du projet

• initModeDev : initialise le mode développement afin de ne pas pourir en dev la base Firebase de production

• images-pre : lance la pre optimisation des images pour les compresser au mieux pour le web

• styles : compile les fichiers Sass en CSS

• blog : convertit les fichiers Asccidoc en HTML et génère également un flux RSS pour le blog

• images : génère les images au format webp qui est un format optimisé pour Chrome

• images-post : copie les images dans le répertoire de sortie

• lint : analyse le code pour détecter les problèmes

• html : génère les pages HTML à partir des sources. Chaque page HTML est intégrée dans un template handlebars pour éviter de toujours déclarer les mêmes entêtes dans tous nos fichiers

• local-js : crée un fichier bundle avec les différents scripts définis dans l’application

• vendor-js : copie les dépendances externes dans le répertoire de sortie

• copy : copie les fichiers statiques (manifest, robot.txt…​) dans le répertoire de sortie

• cache-busting : ajoute un hash à chaque ressource pour limiter les problèmes de cache

• service-worker : génère des services workers pour être capable d’utiliser le site hors ligne

• serveAndWatch : démarre un serveur web pour les tests et active un mode watch pour que les ressources soient automatiquement mises à jour quand elles sont modifiées

Générer le site pour la production

gulp

Cette commande Gulp effectue différentes tâches que tu peux lancer individuellement si tu veux tester une phase particulière de la construction du projet

• images-pre : lance la pre optimisation des images pour les compresser au mieux pour le web

• styles : compile les fichiers Sass en CSS

• blog : convertit les fichiers Asccidoc en HTML et génère également un flux RSS pour le blog

• images : génère les images au format webp qui est un format optimisé pour Chrome

• images-post : copie les images dans le répertoire de sortie

• lint : analyse le code pour détecter les problèmes

• html : génère les pages HTML à partir des sources. Chaque page HTML est intégrée dans un template handlebars pour éviter de toujours déclarer les mêmes entêtes dans tous nos fichiers

• local-js : crée un fichier bundle avec les différents scripts définis dans l’application

• vendor-js : copie les dépendances externes dans le répertoire de sortie

• copy : copie les fichiers statiques (manifest, robot.txt…​) dans le répertoire de sortie

• cache-busting : ajoute un hash à chaque ressource pour limiter les problèmes de cache

• service-worker : génère des services workers pour être capable d’utiliser le site hors ligne

• sitemap : génère le fichier sitemap.xml pour les robots indexeurs