Hugo - Pense-bête

I. Installation

L’installation du logiciel Hugo peut être réalisée en suivant le guide Démarrage rapide.

Le plus simple pour installer Hugo est d’utiliser le gestionnaire de paquets de votre distribution (apt pour Debian, pacmanpour Arch…).

Pour debian :

apt install hugo

Pour Arch Linux :

pacman -S hugo

II. Création de votre site

Toutes les commandes du logiciel Hugo commencent par hugo, exemple pour avoir de l’aide :

hugo help

Pour créer votre site de documentations, il faudra utiliser la commande :

hugo new site quickstart        # remplacer quickstart par le nom de votre site

On se place dans le répertoire quickstart:

cd quickstart

III. Ajout de contenus

Pour ajouter des contenus de type chapitre (chapter) ou page, nous utiliserons les commandes suivantes :

III.1 - Ajout d’un chapitre

Ajout d’un nouveau chapitre qui contiendra une ou plusieurs pages de documentations :

hugo new --kind chapter 01-premiere_doc/_index.md

Modifier le fichier content/01-premiere_doc/_index.md pour que dans l’arborescence du menu, ce chapitre soit affiché en premier :

+++
archetype = "chapter"
title = "01 Premiere Doc"
weight = 1
+++

Vous pouvez changer le titre en modifiant l’option title, celui-ci sera affiché dans le menu à gauche de votre futur site.

III.2 - Ajout d’une page

Pour ajouter une page dans le chapitre précédement créé, utilisez la commande :

hugo new 01-premiere_doc/01-installation.md

IV. Configuration

Voici quelques paramètres de configuration, ceux-ci sont à placer dans le fichier hugo.toml dans le répertoire quickstart.

IV.1 - Paramètres de base

A minima, votre fichier hugo.toml devra contenir ces quatre lignes :

# URL de base
baseURL = 'https://docs.example.com'
# Le language à utiliser par défaut
languageCode = 'fr'
# Le titre de votre site
title = 'My Docs'
# Le thème utilisé - dans mon cas Relearn
theme = 'hugo-theme-relearn'

IV.2 - Désactivation multilangues

Par défaut, le site est créé pour être multilangues, si ce n’est pas le cas ajouter ces options :

# Désactivation de l'option multilangues
IsMultiLingual = 'false'
# On définit le language par défaut des contenus
DefaultContentLanguage = 'fr'
# On désactive le language par défaut des sous-répertoires
DefaultContentLanguageInSubdir = 'false'

IV.3 - Paramètres généraux

Vous pouvez définir des paramètres généraux tels que ceux ci-dessous. Ces paramètres pouront être utilisés dans les différents contenus.

[params]
# Nom de l'auteur des contenus
author.name = 'John Doe'
# On désactive le changement de languages
disableLanguageSwitchingButton = 'true'
# Le titre global de notre site
globalTitle = "My docs"
# L'état initial de développement des sous-menus.
alwaysopen = ''
# Carractère affiché devant chaque nom de chapitre
breadcrumbSeparator = '>'
# Menu rétractable
collapsibleMenu = true
# Désactivation du menu Home affiché sous la barre de recherche
disableLandingPageButton = true
# Désactivation des boutons suivant et précédent
disableNextPrev = false
# Options selon le thème - ici pour Relearn on affiche la possibilité de passer du mode sombre
# au mode clair, le mode sombre étant celui par défaut (premère valeur)
themeVariant = [ "relearn-dark", "relearn-light" ]
# D'autres paramètres qui affectent l'affichage des images
  [params.imageEffects]
    border = false
    lazy = true
    lightbox = true
    shadow = false

IV.4 - Recherche et impression

Pour activer la recherche et afficher le bouton d’impression, veuillez ajouter ces paramètres :

# Activate search
[outputs]
  home = ['html', 'rss', 'print', 'search']
  page = ['html', 'rss', 'print']
  section = ['html', 'rss', 'print']

IV.5 - Personnalisation du thème Relearn

Pour ce thème, j’ai personnalisé une seule chose, j’ai supprimé le logo du thème et renseigné le titre du site.

Cela se fait en éditant le fichier themes/hugo-theme-relearn/layouts/partials/logo.html et en remplaçant le chapitre en fin de page :

<a id="R-logo" href="{{ partial "relLangPrettyUglyURL.hugo" (dict "to" .Site.Home) }}">
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64.044 64.044">
        [...]
    </svg>Relearn
</a>

par :

<a id="R-logo" href="{{ partial "relLangPrettyUglyURL.hugo" (dict "to" .Site.Home) }}">My Docs</a>

V. Publication

Pour générer une version html du site, prête à être publiée sur votre serveur web, utilisez la commande ci-dessous, toujours en étant dans le répertoire quickstart :

hugo

Ensuite il faudra copier le contenu du répertoire public qui contient une copie html de votre futur site.

Voici un exemple, très simplifié d’un script qui pourrait s’occuper de générer la version html de votre site et de la synchroniser dans le répertoire contenant votre site web qui sera affiché à l’aide de Apache ou de Nginx.

#!/bin/bash

rsync -avz --delete ~/quickstart/public/ /var/www/mydocs/
chown -R www-data: /var/www/mydocs/

• ~/quickstart/public/: répertoire ~/quickstart contenant le répertoire public où se trouve la version html de votre site, après avoir exécuté la commande hugo.
• /var/www/mydocs/: répertoire (apache ou nginx) contenant votre site web de documentations
• www-data : utlisateur apache ou nginx

Ces variables sont à adapter selon votre configuration.

VI. Nginx - Fichier de configuration

Voici un fichier minimaliste pour la configuration de ce nouveau serveur web :

server {
  listen 80;
  server_name docs.example.com;

  root /var/www/mydocs;
  index index.html;

  access_log /var/log/nginx/mydocs-access.log main;
  error_log /var/log/nginx/mydocs-error.err;

  port_in_redirect off;

  location / { 
      add_header Cache-Control "public, max-age=3600";
  }   

  location ~ \.(jpg|jpeg|gif|png)$ {
      add_header Cache-Control "public, s-maxage=7776000, max-age=86400";
  }   

  location ~ \.(css|js)$ {
      add_header Cache-Control "public, max-age=31536000";
  }   

  location /assets/fonts/ {
      add_header Cache-Control "public, s-maxage=7776000, max-age=86400";
  }   

  error_page 404 /404.html;

}