Sites statiques

Généralités

Hugo est un générateur de sites statiques. Les sites statiques ont pour avantage d’être plus rapides, plus facilement transférables, plus sûrs, plus écologiques et moins onéreux à héberger. Cette documentation vous apprendra à créer votre site sur le GitLab de TeDomum, à le lier à un nom de domaine que vous possédez, à configurer Git pour le cloner sur votre ordinateur et à le modifier localement avant de le téléverser.

Créer le site sur GitLab

Rendez-vous sur notre forge GitLab ; vous aurez besoin d’un compte TeDomum pour vous connecter.

Dans le menu « Projets » en haut à gauche, sélectionnez « Create from templace », puis sélectionnez le modèle Pages/Hugo sur la page suivante.

La page suivante vous permettra de configurer les paramètres de votre projet :

  1. le nom de votre projet ;
  2. votre nom d’utilisateurice sera utilisé par défaut, mais vous pouvez le modifier si vous êtes membre d’un projet ;
  3. l’identifiant du projet sera, par défaut, le nom du projet en minuscules ;
  4. vous pouvez indiquer une description de votre site ;
  5. vous pouvez choisir si le projet est visible de vous seul-e, de toutes les utilisateurices identifiées ou de tout le monde.

Cliquez sur « Create project » – oui, la traduction est perfectible – afin de valider vos paramètres et de lancer la création du projet.

Configurer et générer le site

  1. Nous allons lier le site à notre nom de domaine. Commencez par sélectionner le fichier config.toml puis, dans la page qui apparaît, cliquez sur « Éditer ». Remplacez le contenu entre " " de la première ligne, baseurl, par l’adresse de votre site sous la forme https://monsite.fr. Validez en cliquant sur « commit changes ».
  2. Rendez-vous ensuite dans les paramètres de « Pages », où vous trouverez un bouton « New Domaine ». Entrez votre nom de domaine dans la case « Domaine » ; vous pouvez laisser le bouton « certificate » enclenché. Cela générera un certificat qui sécurisera les communications avec votre site. Créez le nouveau domaine afin que GitLab vous fournisse les informations à inscrire dans la zone DNS de votre fournisseur de nom de domaine.

Les informations de la case DNS et de la case Verification status sont à copier et coller chez votre fournisseur de nom de domaine. Elles serviront respectivement à faire le lien entre notre GitLab et votre nom de domaine et à vérifier que vous êtes bien le détenteur de ce dernier.
Une fois ces informations reportées chez votre fournisseur, retentez une « Verification status ». Si celle-ci échoue, vérifier que la valeur précédant TXT dans votre zone DNS ne comprend pas deux fois votre nom de domaine, par exemple _gitlab-ages-verification-code-domaine.fr.domaine.fr.
Ces modifications peuvent prendre plusieurs minutes, armez-vous de patience. Tôt ou tard, en visitant l’adresse de votre site, vous arriverez sur la page d’accueil par défaut de Hugo.

Ajouter du contenu à son site

Pour pouvoir modifier son site, nous l’importerons sur notre ordinateur et apprendrons à le modifier localement. Nous utiliserons l’outil git pour l’importation et un éditeur Markdown pour l’édition.
Nous travaillerons sur notre ordinateur avec une prévisualisation locale du site avant d’envoyer les documents modifiés sur le site en ligne.

Configurer GIT

Installez git sur votre ordinateur ; celui-ci est disponible dans les dépôts des distributions Linux. Configurez votre nom d’utilisateurice et votre courriel avec les commandes ci-dessous. Les valeurs à modifier sont indiquées en jaune :

git config --global user.name "NOM"  
git config --global user.email "COURRIEL"

Créons désormais une clef d’authentification SSH qui permettra à GitLab de reconnaître automatiquement notre ordinateur et d’éviter d’avoir à nous connecter à chaque fois :

ssh-keygen -t ed25519 -C "< COMMENTAIRE >"

En remplaçant COMMENTAIRE par la valeur de votre choix : un courriel, TeDomum, etc. Pressez « Entrée », la commande vous retournera les lignes suivantes :

Generating public/private ed25519 key pair.  
Enter file in which to save the key (/home/UTILISATEURICE/.ssh/id_ed25519):

Pressez à nouveau « Entrée » pour valider. Rendez-vous dans le dossier .ssh de votre dossier /home/UTILISATEURICE et ouvrez le fichier id_ed25519.pub pour en copier la valeur. Vous pouvez également utiliser la commande :

cat /home/UTILISATEURICE/.ssh/id_ed25519.pub

Cette valeur doit être collée dans la zone indiquée ci-dessous par un 3.

Copier son site sur l’ordinateur

Ouvrez un terminal dans le dossier de travail que vous souhaitez utiliser puis entrez :

git clone git@forge.tedomum.net:UTILISATEURICE/IdentifiantProjet

Avec votre nom d’utilisateurice et l’identifiant du projet tel que défini en 3 de la troisième capture d’écran de cette documentation. Validez et votre site sera téléchargé.

Installez npm et Hugo ; ceux-ci sont probablement disponibles dans les dépôts de votre distribution Linux.

Pour générer une version locale de votre site, placez-vous dans votre dossier de travail et entrez la commande :

hugo

Désormais, vous pourrez prévisualiser votre site en entrant la commande suivante depuis votre dossier de travail :

hugo server -D

Modifier son site localement

Changer le thème du site

Ouvrez votre gestionnaire de fichiers et rendez-vous dans votre dossier de travail. Choisissez parmi un large choix de thèmes celui qui vous convient. Si vous souhaitez utiliser le thème PaperMod, cliquez sur le bouton Download, téléchargez-le et décompressez l’archive dans le dossier « themes ».

Ouvrez ensuite le fichier config.toml et entrez le NOMDUTHEME à la ligne thème. Si le dossier de notre thème se nomme paper on entrera :

theme = "paper"

Changer l’identité du site

Le fichier config.toml vous permettra de changer le titre title du site, son sous-titre subtitle, ainsi que vos informations personnelles – si vous souhaitez en indiquer – dans la rubrique auteur Author. Il vous permettra en outre de modifier le menu de votre site.

Modifier le menu

Vous verrez au bas du fichier config.toml plusieurs éléments de menu prédéfinis sous la forme

[[menu.main]]  
  name = "nom du sous-menu"  
  url = "sous-menu"  
  weight = chiffre

Le nom, vous l’aurez compris, est le titre que vous souhaitez utiliser pour votre élément de menu. L’url peut être un lien vers un autre site, ou le nom du dossier auquel vous souhaitez lier cet élément de menu. Ce dossier doit se trouver dans le sous-dossier de contenu content de votre répertoire de travail. Le chiffre que vous indiquerez dans la ligne weight indiquera la position de ce sous-menu dans votre menu.
Ainsi, si j’ai dans mon dossier content un sous-dossier intitulé publications que je souhaite placer en troisième position du menu, je créerai cet élément de menu :

[[menu.main]]  
  name = "Mes publications"  
  url = "publications/"  
  weight = 3

Vous pouvez en outre ajouter un sous-menu permettant de retrouver les articles par tags.

[[menu.main]]     
  name = "Tags"     
  url = "tags"     
  weight = 4

Nous vous indiquerons comment trier les pages par tags dans la rubrique suivante.

Ajouter des pages

L’ajout de pages sur votre site se fait depuis le dossier content. Pour ajouter du contenu dans Mes publications – pour reprendre l’exemple ci-dessus –, je me rends dans le dossier publications et crée un fichier intitulé publication1.md.
Nous allons créer un en-tête dans ce fichier :

 ---  
 title: Première publication  
 subtitle: Nous pouvons donner un sous-titre  
 date: 2021-04-27  
 menu: "publications"
 tags: ["océan", "nature"]
 weight = 1
 ---

Les trois tirets ouvrent et ferment l’en-tête. Il est important de préciser le menu dans lequel vous souhaitez qu’apparaisse le fichier afin qu’il soit correctement indexé par Hugo et d’éviter une erreur 404. Le paramètre weight permettra de modifier l’ordre des pages. Les tags sont ajoutés entre " " et séparés par une virgule.
Vous pouvez ensuite écrire le texte que vous souhaitez en suivant la syntaxe Markdown.

Ajouter une page d’accueil

Si vous voulez ajouter une page d’accueil spécifique, vous pouvez créer un dossier intitulé « layouts », dans lequel vous ajouterez une page « index.html » contenant les informations suivantes :

{{ define "main" }}  
    <main aria-role="main">  
      <header class="homepage-header">
        <h1>{{.Title}}</h1>
        {{ with .Params.subtitle }}
        <span class="subtitle">{{.}}</span>
        {{ end }}
      </header>
      <div class="homepage-content">
        <!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
        {{.Content}}
      </div>
      <div>
        {{ range first 10 .Site.RegularPages }}
            {{ .Render "summary"}}
        {{ end }}
      </div>
    </main>
{{ end }}

Vous pourrez désormais modifier votre page d’accueil en modifiant le fichier _index.md à la racine de votre dossier content.

Téléverser son site vers GitLab

Lorsque vous avez terminé de travailler sur votre ordinateur, vous pourrez téléverser votre contenu afin qu’il soit mis en ligne. Ouvrez à nouveau votre terminal et rendez-vous dans votre dossier de travail. Les étapes qui suivent peuvent vous paraître déconcertantes, mais vous vous y habituerez très vite. La première commande à entrer est :

git status

Cela nous apprend que nous avons modifié notre fichier de configuration – config.toml – et que nous avons créé un nouveau dossier qui n’est pas encore pris en compte : content/publications. Commençons par signaler à git que nous voulons qu’il tienne compte de ce dossier en entrant la commande :

git add content/publications

Le terminal ne retourne rien, c’est normal. Entrons ensuite la ligne :

git commit -a

Dans ce fichier, il faudra retirer les # des lignes contenant un fichier que vous souhaitez téléverser. Ici, nous voulons téléverser config.toml et notre première publication.

Sauvegardez votre fichier avec Ctrl+O puis Ctrl+X si vous utilisez nano. Entrez à nouveau git status qui vous indiquera que votre dossier local est en avance par rapport à votre dossier en ligne.

Il ne reste plus qu’à « pousser » notre travail vers GitLab avec la commande :

git push

GitLab analysera les nouveaux fichiers et mettra votre site à jour.

Autres instances

Il existe d’autres instances GitLab. Si vous ne trouvez pas votre bonheur chez nous, peut-être le trouverez-vous ailleurs ?

Vous en trouverez certainement d’autres du côté des chatons.