Générateur de sites statiques : un retour

Pierre Gambarotto

Created: 2023-11-15 mer. 11:40

Utiliser hugo/zola/jekyll/pelican/…

Pour bâtir un site de documentation

Pour bâtir le site complet d’un labo

principe

  • IN : un tas de fichier : sources (markdown, json, xml …), template (html/jinja), theme
  • un compilateur
  • OUT : un tas de fichiers html/css/js = un site statique

IN – compilation -> OUT

déploiement

  • prendre le tas de fichiers OUT
  • un serveur http devant

C’est tout

=> CI

=> gitlab-pages

schéma du rendu d’une page

en fonction du chemin demandé dans la requête

  • sélection d’un document source
  • sélection de template pour le rendu

À maîtriser en tout premier lieu !

Exemple pour hugo : fr/institut/actualites/ed0797aa-655e-4f7c-98b2-de4ad417a4c7/

  • source : content/french/institut/actualités/ed0797aa-655e-4f7c-98b2-de4ad417a4c7.md
  • template : themes/institut/_defaut/single.html

Exemple simple : en zola, doc de la plm

https://plmdoc.math.cnrs.fr/

  • indexation embarquée
  • publication par intégration continue gitlab-pages
  • rédaction en fichier markdown dans un dépôt git
  • principale difficulté pour les rédacteurs : git ^_^’’

Exemple plus complexe

https://www.math.univ-toulouse.fr

demo sur quelques fonctionnalités sympathiques

  • lien avec indico pour les événements, généré automatiquement à partir de la catégorie indico de l’IMT
  • lien avec hal : utiliser la loupe, chercher «besse christophe» => lien géré + indexation
  • annuaire et recherche en live : api perso
  • éditeur de contenu

Utiliser une API externe

Exemple : indico, hal, annuaire

  1. requête API, matérialiser le résultat sous forme de fichiers xml/json/yaml/toml
  2. configurer le générateur pour ce type de fichiers

    avec hugo et zola, ces fichiers sont considérés comme des préambules complets : rien à faire.

{
  "id": "10951",
  "title": "Quid of homology spheres?",
  "description": "<p>The early history of topology began with the ideas of E. Betti and B. Riemann and the work of H. Poincaré on the concept of homology, quickly refined into the concept of homotopy. The infamous Poincaré conjecture (now theorem) states that no compact object has the same homotopy groups as the 3-sphere. But Poincaré originally believed the same about homology. This other conjecture was disproved by Poincaré himself by building a \"homology sphere\", a 3-dimensional object not homeomorphic to the 3-sphere but with the same homology groups. In this talk we present another method of building this homology sphere due to M. Dehn. This construction makes use of elementary tools from knot theory, homotopy and of course homology, which we present along the way.</p>",
  "startDate": {
    "date": "2023-11-15",
    "time": "18:00:00",
    "tz": "Europe/Paris"
  },
  "timezone": "Europe/Paris",
  "endDate": {
    "date": "2023-11-15",
    "time": "19:00:00",
    "tz": "Europe/Paris"
  },
  "room": "Room Picard (1R2-129)",
  "type": "events",
  "references": [],
  "categoryId": 607,
  "category": {
    "name": "Séminaire QUID",
    "id": "607"
  },
  "roomFullname": "Room Picard (1R2-129)",
  "creationDate": {
    "date": "2023-11-11",
    "time": "18:10:05.158689",
    "tz": "Europe/Paris"
  },
  "creator": "Saint-Criq, Anthony",
  "chairs": [
    {
      "lastName": "Rodau",
      "firstName": "Adrien",
      "fullName": "Rodau, Adrien"
    }
  ],
  "keywords": [],
  "link": "https://indico.math.cnrs.fr/event/10951/",
  "evenements": [
    "seminaires"
  ],
  "eventFamily": "seminaires",
  "recurrentData": {
    "_fossil": "categoryMetadata",
    "type": "Category",
    "name": "Séminaire QUID",
    "id": 607,
    "url": "https://indico.math.cnrs.fr/category/607/"
  },
  "recurrentEvent": [
    "607"
  ],
  "date": "2023-11-15T18:00:00+01:00",
  "start": "2023-11-15T18:00:00+01:00",
  "end": "2023-11-15T19:00:00+01:00"
}

{
  "sn": "Gambarotto",
  "givenname": "Pierre",
  "cn": "Pierre Gambarotto",
  "id": "865d8574-b1b1-44c2-a371-fee21b79bdcf",
  "ldapAttrMap": {
    "givenname": "Prénom",
    "imtrole": "Fonction",
    "sn": "Nom",
    "buildingname": "Bâtiment",
    "telephonenumber": "Téléphone",
    "mail": "Mail",
    "jpegphoto": "Image",
    "roomnumber": "Numéro de salle",
    "description": "Description"
  },
  "mail": "Pierre.Gambarotto@math.univ-toulouse.fr",
  "imtrole": [
    "Ingénieur de Recherche"
  ],
  "personalwebpage": "http://bla.bli.fr",
  "jpegphoto": "https://profil.math.univ-toulouse.fr/api/public/v1/media/public?ressource=e4307d6c-2e2f-4053-9724-03315063db44.jpg",
  "description": "Télétravaille le lundi et le vendredi",
  "group": "Personnel Administratif et Technique",
  "telephonenumber": "+33659545831",
  "roomnumber": "221",
  "buildingname": "1R3",
  "relativeLink": true,
  "link": "/fr/annuaire/865d8574-b1b1-44c2-a371-fee21b79bdcf",
  "title": "Pierre Gambarotto"
}

hugo : dénicher le template

Implémentation

une API = un script produisant des fichiers dans un répertoire cible.

par ex : annu.sh génère le contenu de content/annuaire

Au niveau du déploiement, il faut donc prévoir

  • une actualisation des fichiers
  • optimiser pour reprendre à partir du résultat précédent
  • ne pas détruire l’existant si l’API ne répond pas

Indexation

Javascript obligatoire côté client.

flux à partir du client :

couche js : interroge un index, soit local soit API

  • client : par exemple elasticlunr
  • backend : par exemple meilisearch

dans les 2 cas, l’index est mise à jour au moment où on calcule le site.

Utilisation d’un service backend

await fetch("https://www.math.univ-toulouse.fr/api/public/search?limit=15&offset=0&query=besse", {
    "credentials": "include",
    "headers": {
        "User-Agent": "Mozilla/5.0 (X11; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/117.0",
        "Accept": "application/json",
        "Accept-Language": "fr,en;q=0.5",
        "Content-Type": "application/json",
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
        "Access-Control-Allow-Headers": "X-Requested-With, content-type, Authorization",
        "Sec-Fetch-Dest": "empty",
        "Sec-Fetch-Mode": "cors",
        "Sec-Fetch-Site": "same-origin",
        "Sec-GPC": "1"
    },
    "referrer": "https://www.math.univ-toulouse.fr/fr/recherche/productions-scientifiques/publications/",
    "method": "POST",
    "mode": "cors"
});

Le résultat de l’appel doit être présenté dans la page :

  • composant js frontend nécessaire

Mode dégradé

L’interrogation de l’index peut échouer :

  • problème javascript sur le client, par ex javascript désactivé
  • partie backend inaccessible ou qui retourne un résultat inexploitable.

Dans les 2 cas, il faut que le site reste lisible.

Éditeur

  • gère les fichiers sources, typiquement markdown
  • git commit
  • déploiement nouvelle version : on appelle le générateur de site statique

Codage

i.e. pas le remplissage du site !

  • 20% : backend/asr :
    • générer des fichiers de contenu par des scripts
    • déploiement
  • 80% : frontend
    • template
    • CSS
    • javascript

Conseils

i.e. ce que je referais différemment

-theme, template et CSS : favoriser une approche composant.

  • html et css : c’est un métier

n’hésitez pas à vous faire aider/à embaucher sur cette partie

Conseils bis

  • javascript : vue/react/le dernier truc à la mode : fatigue …

=> générer des fragments html dans les ressources statiques de votre site

=> htmx pour les insérer dynamiquement

  • javascript pour des composants riches : si vous faites un éditeur de contenu, se baser sur prosemirror