Hugo

Table des matières

Un site statique c’est quoi ?

Plus besoin de PHP, de base de données, c’est un gain de vitesse apréciable.
Par contre, le site doit être regénéré entièrement à chaque ajout d’articles.
Le principe est simple, plus de partie administration, on écrit les articles dans un language de type wiki : le Markdown (md).
Le moteur va ensuite générer le code souhaité (HTML, XML, JSON), à l’aide de templates rédigés par l’auteur.
Une arborescence est constituée, il suffit d’envoyer le tout sur votre serveur web via FTP, RSYNC, SFTP.

Installation sous Debian

Rendez-vous sur le site Hugo releases pour télécharger la dernière version (hugo_0.31.1_Linux-64bit.deb) puis installez-la.

# dpkg -i hugo_0.31.1_Linux-64bit.deb

Si vous souhaitez utiliser la coloration syntaxique dans le code, installez également python3-pygments :

# apt-get install python3-pygments

Vérifier l’installation correcte en tapant :

$ hugo version

Votre “moulinette” est prête à fonctionner et à générer des pages.
Pour obtenir de l’aide sur les commandes :

$ hugo help

Création du site

Une seule commande suffit :

$ hugo new site `mon_blog`  

Hugo construit alors une arborescence dans le répertoire du site :

archetypes - config.toml - content - data - layouts - public - static - themes

La structure du site

  • archetypes : permet de définir les front matter par défaut pour les différents types de contenu.
  • config.toml : le fichier de configuration du site.
  • content : le contenu de votre site, comme les pages ou les articles.
  • data : les fichiers de données structurées (inutile pour un blog).
  • layouts : les fichiers personnalisés définissant la structure des pages (accueil, articles, listes).
  • public : les pages statiques générées qu’il faudra publier sur votre site web.
  • static : les fichiers qui ne changent pas (styles css, JavaScript et images).
  • themes : les fichiers de configuration du thème.

Écrire un article

$ hugo new /post/toto.md

Cette commande va créer un nouveau fichier nommé test.md contenant les informations de l’article dans le répertoire /content/post/. Cet article est accessible à l’url localhost:1313/post/test/.
Une fois le fichier article créé, ouvrez-le dans un éditeur texte.

Le fichier article se comporte de deux parties :

  • Le Front Matter, entouré de signes +++
  • Le contenu de l’article lui-même, rédigé au format Markdown

Voici un exemple de Front Matter :

+++
tags = ["Debian"]
categories = ["Outils"]
title = "Autologin"
date = "2012-12-29"
+++

Le front matter contient les informations de l’article : la date, le titre, l’url, la description, le statut (draft ou publié), les tags et catégories.
Maintenant, il ne reste plus qu’à écrire votre article au format Markdown.

Ajouter un thème

Allez sur le répertoire des thèmes Hugo et choisissez un thème (j’utilise le thème academic modifié).
Suivez la procédure expliquée sur la page de ce thème.

Configurer le site

Le fichier config.toml contient tous les paramètres spécifiques au site : nom, url nom du thème, etc.
Exemple

baseurl = "url_du_site" 
title = "titre_du_site"
copyright = "© 2017 votre_nom"
theme = "academic"
enableEmoji = true
footnotereturnlinkcontents = "<sup>^</sup>"
ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]
preserveTaxonomyNames = true
paginate = 10

# Activer les commentaires en indiquant l'identifiant Disqus
disqusShortname = "identifiant_disqus"

# langue par défaut (si vous utilisez le support multilingue)
defaultContentLanguage = "fr"
defaultContentLanguageInSubdir = false

[outputs]
  home = [ "HTML", "CSS", "RSS" ]
  section = [ "HTML", "RSS" ]

# Configurer les BlackFriday Markdown.
# Voir : https://gohugo.io/readfiles/bfconfig/
[blackfriday]
  hrefTargetBlank = true  # `true` ouvre les liens dans un nouvel onglet
  fractions = true  # `false` disables smart fractions (e.g. 5/12 formatted as a fraction).
  smartypants = true  # `false` disables all smart punctuation substitutions (e.g. smart quotes, dashes, fractions).

[params]
  # Couleur du thème.
  # Options : `default`, `ocean`, `forest`, `coffee`, or `dark`.
  color_theme = "coffee"

  # Style de police.
  # Options `default`, `classic`, or `playfair`.
  font = "playfair"

  # Présentation.
  name = "votre_nom"
  role = "votre_role"

  # Organisations/Affiliations.
  # Séparer les entrées avec un comma, utiliser cette forme : `[ {name="Org1", url=""}, {name="Org2", url=""} ]`.
  organizations = [ { name = "votre_organisation", url = "" } ]

  gravatar = false  # importer votre gravatar de Gravatar.com? (true/false)
  avatar = "portrait.jpg"  # Spécifier une image (dans le dossier `static/img/` ) ou ne rien mettre pour enlever l'avatar.
  email = "votre_email"
  address = "votre_adresse"

  # Afficher un logo plutôt que le titre dans la barre de navigation (optionnel).
  #  Pour l'activer, placer une image dans `static/img/` et faire le lien. Pour désactiver, laisser la valeur à "".
  logo = ""

  # Activer/désactiver la carte dans le widget Contact.
  # Pour voir votre adresse sur la carte, entrer la latitude, longitude et choisir un fournisseur.
  # Pour utiliser  Google Maps, set `map = 1` and entrer votre clé API.
  #   https://developers.google.com/maps/documentation/javascript/get-api-key
  # Pour utiliser  OpenStreetMap, set `map = 2`.
  # Pour utiliser OpenStreetMap sur un  site à haut traffic , set `map = 3` et entrer la clé API ; la chercher sur:
  #   https://www.mapbox.com/studio/account/tokens
  # Pour obtenir vos coordonnées, click droit sur Google Maps et choisir  "What's here?". Les coordonnées sont au bas de page.
  #
  # Map provider:
  #   0: No map
  #   1: Google Maps
  #   2: OpenStreetMap (Mapnik)
  #   3: OpenStreetMap (Mapbox)
  map = 2
  map_api_key = ""
  latitude = "49.581904"
  longitude = "2.081580"
  zoom = 15

  # Format de date et d'heure (référence sur : http://fuckinggodateformat.com )
  #   Exemple : "Mon, Jan 2, 2006" ou "2006-01-02"
  # date_format = "Jan 2, 2006"
   date_format = "02/01/2006"
  # date_format = "02 Jan 2006"
  #   Exemples: "3:04 pm" ou "15:04"
  # time_format = "3:04 PM"
  time_format = "15H04"

  # Show estimated reading time for posts?
  reading_time = true

  # Afficher le nombre de commentaires
  comment_count = true


  # Coloration syntaxique

  highlight = true
  highlight_languages = []
   highlight_style = "github"
  # highlight_style = ""

  # Afficher les boutons des réseaux sociaux
  sharing = true

  # Liens pour un CSS personalisé et JS assets
  #   (relatif à  /static/css and /static/js respectively)
  custom_css = []
  custom_js  = []

  # Type de publication.
  #   Utiliser la catégorie des publications.
  #   L'index du type de publication dans la liste est utilisé avec un identifiant numérique.
  #   L'ID est utilisé dans une  publication's frontmatter pour le catégoriser.
  #   La langue peut être éditée au dessous.
  #   Pour un site multilingue, copier ce block pour chaque langue à la fin de ce fichier .

  publication_types = [
    'Uncategorized',  # 0
    'Conference proceedings',  # 1
    'Journal',  # 2
    'Work in progress',  # 3
    'Technical report',  # 4
    'Book',  # 5
    'Book chapter'  # 6
  ]

  # Configuration of talk pages.
  [params.talks]
    # Show talk time?
    time = true

  # Configuration of publication pages.
  [params.publications]
    # Date format (refer to Go's date format: http://fuckinggodateformat.com )
    #   Examples: "Mon, Jan 2, 2006" or "2006-01-02"
    date_format = "January, 2006"

  # Configuration of project pages.
  [params.projects]
    # List publications and talks related to the project?
    list_children = true

    # Publication list format.
    #   0 = Simple
    #   1 = Detailed
    #   2 = APA
    #   3 = MLA
    publication_format = 3

  # Réseaux sociaux  

  [[params.social]]
    icon = "envelope"
    icon_pack = "fa"
    link = "mailto:votre_email"


  [[params.social]]
    icon = "github"
    icon_pack = "fa"
    link = "//github.com/identifiant_github"


  [[params.social]]
    icon = "facebook"
    icon_pack = "fa"
    link = "//facebook.com/patrice.blondel"

# Liens de navigation
#   Pour faire un lien avec un widget, spécifier son  URL as a hash `#` suivi du nom du widget désiré
#    dans le répertore  `content/home/`.
#   Le paramètre weight définit l'ordre d'affichage dans le menu.
[params.menus]
 # Align the main menu to the right of the page? (true/false)
  align_right = true

[[menu.main]]
  name = "Articles"
  url = "#posts"
  weight = 1

[[menu.main]]
  name = "Catégories"
  url = "#categories"
  weight = 2

[[menu.main]]
  name = "Mots-clés"
  url = "#tags"
  weight = 3

[[menu.main]]
  name = "Cours"
  url = "#projects"
  weight = 4

[[menu.main]]
  name = "Contact"
  url = "#contact"
  weight = 5

# Taxonomies.
[taxonomies]
  tag = "tags"
  category = "categories"
  publication_type = "publication_types"

# Langages
#   Créer un block  [languages.X] pour chanque langue désirée , où X est l'ID de la langue.

# Configurer la version française du site.
[Languages.fr]
  languageCode = "fr-fr"

Générer les pages statiques

$ hugo

Cette simple commande générera les pages dans le répertoire public.

Afficher son site en local

$ hugo server -D

Cette commande permet de visionner le site à l’adresse http://localhost:1313/hugo/

Started building sites ...

Built site for language fr:
0 draft content
0 future content
0 expired content
128 regular pages created
72 other pages created
0 non-page files copied
81 paginator pages created
49 tags created
10 categories created
0 publication_types created
total in 239 ms
Watching for changes in /home/govez/public_html/hugo/{data,content,layouts,static,themes}
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/hugo/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Déployer le site sur le web

Afin d’envoyer les pages générées sur mon espace web, j’ai créé un petit script qui utilise lftp.
Pour mettre à jour le site, je le lance à chaque nouvelle publication.

$ ./synchro.sh

Le script synchro.sh pour l’hébergeur Hosteur :

#!/bin/sh
LFTP=$(which lftp) 
$LFTP -c "set ssl:verify-certificate no;     
open ftp://identifiant_ftp:motdepasse_ftp@clusterftp.hosteur.com; 
set net:limit-rate 25000 
lcd /home/govez/public_html/academic/public; 
cd /httpdocs/hugo; 
mirror --continue --reverse --dereference --parallel=5 --delete --verbose"