Construire une bibliothèque avec Hugo

Cet article est une débauche. Vous pouvez m’aider à l'améliorer.

Cadre

exploration JAMstack pour construire une Bibliothèque en ligne.

Source : https://gohugo.io/overview/quickstart/

1. 1. Construire une bibliothèque avec Hugo

Dans ce guide de démarrage rapide, nous construirons une bibliothèque en ligne qui listera des livres et leurs critiques.

> _Note : Ce guide de démarrage rapide dépend de fonctionnalités présentées dans la version Hugo v0.19. Si vous avez une version plus ancienne de Hugo, vous devrez la [mettre à jour](https://gohugo.io/overview/installing/) avant de démarrer._

Étape 1. Installer Hugo

Allez sur [Hugo Releases](https://github.com/spf13/hugo/releases) et téléchargez la version appropriée pour votre OS et votre architecture.

Sauvegardez l’exécutable principal sous `hugo` (ou `hugo.exe` sur Windows) quelques part dans votre `PATH` car nous l’utiliserons dans la prochaine étape.

Des instructions plus complètes sont disponibles sur [Installing Hugo](https://gohugo.io/overview/installing/).

Si vous êtes sur Windows, ce guide de démarrage rapide suppose que vous utilisez [Git Bash](https://git-for-windows.github.io/) (connu aussi comme Git pour Windows). Par conséquent, toutes les commandes commenceront avec le signe Bash (qui est `$`).

Une fois `hugo` installé, assurez-vous de lancer la commande `help` pour vérifier l’ installation d’`hugo`. Vous pouvez voir ci-dessous une partie de la sortie commande `help`.

   $ hugo help
   
   
   hugo is the main command, used to build your Hugo site.
   
   Hugo is a Fast and Flexible Static Site Generator
   built with love by spf13 and friends in Go.
   
   Complete documentation is available at http://gohugo.io/.
   

You can check `hugo` version using the command shown below.

   $ hugo version
   
   
   Hugo Static Site Generator v0.15 BuildDate: 2015-11-26T11:59:00+05:30
   

Étape 2. Échafaudez le site hugo bookshelf

Hugo dispose de commande nous permettant d’échafauder rapidement un site web géré par Hugo. Naviguez vers un endroit pratique sur votre système de fichiers et créez un nouveau site Hugo `bookshelf` en exécutant la commande qui suit.

   $ hugo new site bookshelf
   

Changez de répertoire et allez vers `bookshelf` et vous verrez l’arborescence suivante :

   $ tree -a
   
   
       .
       .
   ├── archetypes
   ├── config.toml
   ├── content
   ├── data
   ├── layouts
   ├── static
   └── themes

   6 directories, 1 file
   

Comme je l’évoquais dans l’output de commande, le répertoire `bookshelf` a 6 sous-répertoires et 1 fichier (`config.toml`). Regardons-les un par un.

 * **archetypes** : Vous pouvez créer de nouveaux fichiers de contenus dans Hugo en utilisant la commande `hugo new`. Quand vous lancez cette commande, cela ajoute quelques propriétés de configuration au post comme la date et le titre. L’[Archetype](https://gohugo.io/content/archetypes/) vous permet de définir vos propres propriétés de configuration qui seront ajoutées au front-matter du post à chaque fois qu’une commande `hugo new` est utilisée.

 * **config.toml** : Chaque site web devrait avoir un fichier de configuration à la racine. Par défaut, le fichier de configuration est au format `TOML` mais vous pouvez aussi utiliser les formats `YAML` ou `JSON`. [TOML](https://github.com/toml-lang/toml) est le format de fichier de configuration minimal qui reste facile à lire du fait d’une sémantique évidente. Les réglages de configuration mentionnés dans le fichier `config.toml` sont appliqués à la totalité du site. Ces réglages de configuration comprennent les `baseURL` et `title` du site web.

 * **content** : C'est là que vous stockerez le contenu du site Web. À l'intérieur du contenu, vous allez créer des sous-répertoires pour différentes sections. Supposons que votre site comporte trois sections - `blog`,` article` et `tutoriel`, alors vous aurez trois répertoires différents pour chacun d'eux dans le répertoire` content`. Le nom de la section, à savoir `blog`,` article` ou `tutoriel`, sera utilisé par Hugo pour appliquer un layout spécifique applicable à cette section.
 
 * **data** : Ce répertoire est utilisé pour stocker les fichiers de configuration qui peuvent être utilisés par Hugo lors de la génération de votre site Web. Vous pouvez écrire ces fichiers au format YAML, JSON ou TOML.

   * **layouts** : Le contenu dans ce répertoire est utilisé pour spécifier la façon dont votre contenu sera converti dans le site Web statique.

   * **static** : Ce répertoire est utilisé pour stocker tout le contenu statique dont votre site web aura besoin comme des images, CSS, JavaScript ou autre contenu statique.

Étape 3. Ajouter du contenu

Ajoutons maintenant un point à notre `bookshelf`. Nous utiliserons la commande `hugo new` pour ajouter un post. En janvier, j’ai lu le livre [Good To Great](http://www.amazon.com/Good-Great-Some-Companies-Others/dp/0066620996/) par conséquent nous commencerons par créer un post pour ça. **Assurez-vous que vous êtes bien dans le répertoire `bookshelf`.**

   $ hugo new post/good-to-great.md
   
   
   /Users/shekhargulati/bookshelf/content/post/good-to-great.md created
   

La commande ci-dessus créera un nouveau répertoire `post` à l’intérieur du répertoire `bookshelf/content` et créera un fichier `good-to-great.md` à l’intérieur.

   $ tree -a content
   
   
   content
   `-- post
       `-- good-to-great.md
   
   1 directory, 1 file
   

Le contenu dans le fichier `good-to-great.md` ressemble à ce qui suit en-dessous.

   +++
   date = "2017-03-08T12:29:06+01:00"
   title = "good to great"
   draft = true

   +++
   

Le contenu à l'intérieur de `+++` est la configuration de TOML pour le message. Cette configuration est appelée **front matter**. Elle vous permet de définir la configuration du post avec son contenu. Par défaut, chaque post aura les trois propriétés de configuration indiquées ci-dessus.

 * **date** spécifie les date et heure à laquelle ce post a été créé.
 * **draft** spécifie que le post n’est pas prêt pour la publication à cette heure, aussi il ne sera pas dans le site généré.
 * **title** spécifie le titre du post.

Ajoutons une petite critique pour le livre **Good to Great**.

   +++
   date = "2016-02-14T16:11:58+05:30"
   draft = true
   title = "Good to Great Book Review"
   
   +++
   
   J’ai lu la version française de **Good to Great en janvier 2013** (De la performance à l’excellence). Même si le livre n’est plus adapté à l’ère numérique, il demeure une référence dans les ouvrages de management que je recommande aux chefs d’entreprises dans le creux de la vague. Plein de bons conseils. La [méthode Hérisson](http://blog-du-consultant.fr/le-consultant-freelance-et-le-concept-du-herisson/).
   

Étape 4. Servez le contenu

Hugo a un serveur intégré qui peut servir votre contenu de site web afin de le pré-visualiser. Vous pouvez aussi utiliser le serveur Hugo intégré en production. Pour servir le contenu, exécutez la commande suivante à l’intérieur du répertoire `bookshelf`.

   $ hugo server
   Started building sites ...
   =============================================================
   Your rendered home page is blank: /index.html is zero-length
    * Did you specify a theme on the command-line or in your
      "." file?  (Current theme: "")
    * For more debugging information, run "hugo -v"
   =============================================================
   Built site for language en:
   0 of 1 draft rendered
   0 future content
   0 pages created
   0 paginator pages created
   0 tags created
   0 categories created
   in 9 ms
   Watching for changes in /Users/shekhargulati/bookshelf/{data,content,layouts,static}
   Serving pages from memory
   Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
   Press Ctrl+C to stop
   

Ceci démarrera le serveur sur le port `1313`. Vous pouvez voir votre blog sur [1](http://localhost:1313/). Quand vous cliquerez sur le lien, vous ne verrez rien. Plusieurs raisons à cela :

 1. Comme vous pouvez le voir dans l’output de la commande `hugo server`, Hugo n’a pas affiché le « draft ». Hugo ne rendra les drafts que si vous passez le flag  `buildDrafts` dans la commande `hugo server`.
 2. Nous n’avons pas spécifié comment le contenu Markdown devrait être restitué. Nous devons spécifier un thème que peut utiliser Hugo. Nous ferons ça à la première étape.
 

Pour restituer les drafts, relancer le serveur avec la commande présentée en-dessous.

   $ hugo server --buildDrafts
   
   
   1 of 1 draft rendered
   0 future content
   0 expired content
   1 regular pages created
   2 other pages created
   0 non-page files copied
   0 paginator pages created
   0 tags created
   0 categories created
   total in 4 ms
   Watching for changes in /Users/xtof/sites/bookshelf/{data,content,layouts,static}
   Serving pages from memory
   Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
   Press Ctrl+C to stop
   

Et si vous allez sur [2](http://localhost:1313/), vous ne verrez toujours rien car nous n’avons pas spécifié un thème que devrait utiliser Hugo.

Étape 5. Ajoutez un thème

Les thèmes fournissent la mise en page et les modèles qui seront utilisés par Hugo pour rendre votre site Web. Il existe de nombreux thèmes Open-source disponibles à [3](https://themes.gohugo.io/) que vous pouvez utiliser.

> **Hugo ne propose pas actuellement de thème `default`, permettant à l'utilisateur de choisir le thème le mieux adapté à son projet.**

Les thèmes doivent être ajoutés dans le répertoire `themes` à l'intérieur de la racine du référentiel.

   $ cd themes
   

Vous pouvez maintenant cloner un ou plusieurs thèmes dans le répertoire `themes`. Nous utiliserons le thème `robust`, mais à un commit (dans son historique) qui fonctionne avec ce guide quickstart.

   $ git clone https://github.com/dim0627/hugo_theme_robust.git
   $ (cd hugo_theme_robust; git checkout b8ce466)
   

Quittez le répertoire thèmes.

   $ cd ..
   

Redémarrez le serveur.

   $ hugo server --theme=hugo_theme_robust --buildDrafts
   
   1 of 1 draft rendered
   0 future content
   0 expired content
   1 regular pages created
   2 other pages created
   0 non-page files copied
   2 paginator pages created
   0 tags created
   0 categories created
   total in 9 ms
   Watching for changes in /Users/xtof/sites/bookshelf/{data,content,layouts,static,themes}
   Serving pages from memory
   Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
   Press Ctrl+C to stop
   

> _Note : Si Hugo ne trouve pas le thème spécifié dans le répertoire `themes`, il affichera une exception comme ci-dessous : > > FATAL: 2016/02/14 Unable to find theme Directory: /Users/shekhargulati/bookshelf/themes/robust >

Pour voir votre site web, vouvez aller sur [4](http://localhost:1313/). Vous verrez ce qui s’affiche ci-dessous.


Comprenons la mise en page du thème. Un thème est constitué des éléments suivants :

 * **theme.toml** est le fichier de configuration du thème qui donne l’information sur le thème comme les nom et description du thème, les détails de l’auteur et la licence du thème.

 * le répertoire **images** contient deux images – `screenshot.png` et `tn.png`. `screenshot.png` est l’image de la vue liste et  `tn.png` est la vue d’un post unique.

 * le répertoire **layouts** contient différentes vues pour différents types de contenus. Chaque type de contenu devrait avoir deux fichiers `single.html` et `list.html`. `single.html` est utilisé pour restituer une pièce unique de contenu.`list.html` est utilisée pour visualiser une liste d’items de contenu. Par exemple, vous utiliserez `list.html` pour voir tous les posts qui ont le tag `programmation`.

 * le répertoire **static** stocke tous les actifs statiques utilisés par le template. Les actifs statiques pourraient être des bibliothèques JavaScript comme  jQuery ou des styles CSS ou des images, ou tout autre contenu statique. Ce répertoire sera copié à l’intérieur du site final une fois restitué.

1. 1. Étape 6. Utilisez plusieurs thèmes

Vous pouvez tester très facilement différentes mises en page en basculant entre différents thèmes. Supposons que nous voulions essayer le thème `bleak`. Nous clonons le thème `bleak` dans le répertoire `bookshelf/themes`.

   $ git clone https://github.com/Zenithar/hugo-theme-bleak.git
   

Redémarrez le serveur en utilisant `hugo-theme-bleak` comme affiché ci-dessous.

   $ hugo server --theme=hugo-theme-bleak --buildDrafts
   

Désormais, le site web utilisera le thème `bleak` et sera restitué différemment comme sur l’image ci-dessous.


1. 1. Étape 7. Mettez à jour `config.toml` et le rechargement live en action

Redémarrez le serveur avec le thème `robust`, car nous l’utiliserons dans ce guide quickstart.

   $ hugo server --theme=hugo_theme_robust --buildDrafts
   

Le site web utilise les valeurs stupides spécifiées dans le fichier `bookshelf/config.toml`. Mettons à jour la configuration.

   languageCode = "fr-fr"
   title = "La bibliothèque de la Maison Ducamp"
   baseURL = "http://ducamp.me"

   [Params]
     Author="Christophe Ducamp"

Hugo a un support intégré pour un rechargement live. Ainsi, dès que vous sauvegardez vos modifications, cela appliquera le changement et rechargera la page web. Vous verrez les modifications comme affichées ci-dessous.


The same is reflected in the Hugo server logs as well. As soon as you changed the configuration file, Hugo applied those changes to the affected pages.

   Config file changed: /Users/xtof/Sites/bookshelf/config.toml
   Started building sites ...
   Built site for language en:
   1 of 1 draft rendered
   0 future content
   0 expired content
   1 regular pages created
   2 other pages created
   0 non-page files copied
   2 paginator pages created
   0 tags created
   0 categories created
   total in 34 ms    

1. 1. Étape 8. Personnalisez le thème robust

Le thème `robust` est un bon point de départ pour notre bibliothèque en ligne mais nous voulons le personnaliser un peu pour satisfaire le look and feel requis pour la bibliothèque. Hugo rend très facile la personnalisation des thèmes. Vous pouvez aussi créer vos thèmes mais nous ne ferons pas ça aujourd’hui. Si vous voulez créer votre propre thème, alors vous devriez vous référer à la [documentation Hugo](https://gohugo.io/themes/creation/).

Le premier changement que nous devons faire, c’est utiliser une image par défaut au lieu de celle utilisée par le thème. L’image du thème par défaut est utilisée à la fois dans la liste et dans les pages en vue unique et elle réside dans `themes/hugo_theme_robust/static/images/default.jpg`. Nous pouvons facilement la remplacer en créant une structure de répertoire simple dans le répertoire `static` du référentiel.

Créez un répertoire `images` dans le répertoire `bookshelf/static` et copiez à l'intérieur une image avec le nom `default.jpg`. Nous utiliserons l'image par défaut ci-dessous.


Hugo va synchroniser les modifications et recharger le site Web pour utiliser une nouvelle image comme illustré ci-dessous.


Maintenant, nous devons changer la disposition de la page d'index afin que seules les images soient montrées au lieu du texte. Le fichier `index.html` à l'intérieur du répertoire layouts du thème se réfère au partial `li` qui rend la vue de la liste ci-dessous.

   <article class="li">
     

         Modèle:With .Site.Params.DateFormModèle:$.Date.Format .Modèle:ElseModèle:$.Date.Format "Mon, Jan 2, 2006"Modèle:End

Modèle:.Title

Modèle:.Summary

     
   </article>
   

Créez un nouveau fichier `li.html` dans le répertoire `bookshelf/layouts/_default` directory. Copiez le contenu présenté ci-dessous à l’intérieur du fichier `li.html`. Nous avons retiré les détails du livre afin que seule l’image soit affichée.

   <article class="li">
     

     
   </article>
   

Maintenant, le site web sera restitué comme ci-dessous.


Puis, nous voulons retirer l’information liée au thème dans le pied de page. Pour faire ça, créez un nouveau répertoire `partials` à l’intérieur de `bookshelf/layouts`. Là, créez un nouveau fichier `default_foot.html` avec le contenu copié à partir du thème `layouts/partials/default_foot.html`. Remplacez la section footer avec celle affichée en-dessous.

   <footer class="site">

Modèle:With .Site.Copyright{{ . }}Modèle:Else© Modèle:$.Site.LastChange.Year Modèle:If isset $.Site.Params "Author"Modèle:$.Site.Params.AuthorModèle:ElseModèle:.Site.TitleModèle:EndModèle:End

Motorisé par Hugo,

   </footer>
   

Nous devons aussi retirer la barre latérale sur la droite. Copiez le fichier `index.html` à partir du répertoire du thème `layouts` vers le répertoire  `bookshelf/layouts`. Retirez la section en rapport avec la barre latérale du HTML :

     Modèle:Partial "sidebar.html" .

À ce stade, nous utilisons l'image par défaut mais nous aimerions utiliser l'image du livre afin de la relier au livre. Chaque critique de livre définira un réglage de configuration dans son front matter. Mettez à jour le fichier `good-to-great.md` comme indiqué ci-dessous.

   +++
   date = "2016-02-14T16:11:58+05:30"
   draft = true
   title = "Good to Great Book Review"
   image = "good-to-great.jpg"
   +++
   
   I read **Good to Great in January 2016**. An awesome read sharing detailed analysis on how good companies became great. Although this book is about how companies became great but we could apply a lot of the learnings on ourselves. Concepts like level 5 leader, hedgehog concept, the stockdale paradox are equally applicable to individuals.
   

Trouvez une image (légale) quelque part, nommez-la `good-to-great.jpg`, et placez-la dans le répertoire `bookshelf/static/images`.

Après avoir ajouté quelques livres sur votre étagère, l'étagère apparaît comme ci-dessous. Ce sont quelques livres que j'ai lus l'année dernière.


1. 1. Étape 9. Rendez les posts publics

À ce stade, tous les posts que nous avons écrits sont au statut d’ébauche (draft). Pour faire qu’un draft soit public, vous pouvez soit lancer une commande ou changer manuellement le statut draft dans le post en `false`.

   $ hugo undraft content/post/good-to-great.md
   

Maintenant, vous pouvez démarrer le serveur sans l’option `buildDrafts`.

   $ hugo server --theme=hugo_theme_robust
   

1. 1. Étape 10. Intégrez Disqus

Disqus vous permet d'intégrer les commentaires dans votre blog statique. Pour activer Disqus, vous devez simplement régler `disqusShortname` dans le fichier `config.toml` comme indiqué en-dessous.

   [Params]
     Author = "xtof"
     disqusShortname = <your disqus shortname>
   

Désormais, le commentaire sera activé sur votre blog.


1. 1. Étape 11. Générer le site web

Pour générer la source du site web Hugo que vous pouvez utiliser sur les pages GitHub, modifiez d’abord `bookshelf/config.toml`, en changeant la ligne `baseURL` en :

   baseURL = "https://<votre-nom-utilisateur-GitHub>.github.io/bookshelf/"
   

Puis tapez la commande qui suit.

   $ hugo --theme=hugo_theme_robust
   
   
   0 draft content
   0 future content
   5 pages created
   2 paginator pages created
   0 tags created
   0 categories created
   in 17 ms
   

Après avoir lancé la commande `hugo`, un répertoire `bookshelf/public` sera créé contenant la source du site web généré.

En passant (au cas où vous auriez essayé), le site web n’est proprement accessible via le protocole `file:///`.

1. 1. Étape 12. Déployez bookshelf sur GitHub pages

Placez le contrôle de version sur votre bookshelf :

   $ git init
   $ echo "/public/" >> .gitignore
   $ echo "/themes/" >> .gitignore
   $ git add --all
   $ git commit -m "Initial commit"
   

Désormais, les repositories Git sous `bookshelf/themes` ne seront pas en conflit avec votre repository `bookshelf`, et un repo Git ne sera pas non plus en conflitdans le `bookshelf/public`.

Créez un nouveau repository sur GitHub appelé `bookshelf` (sans README). Une fois que c’est fait, créez un nouveau repository Git sur votre système local dans `bookshelf/public` et ajoutez remote :

   $ cd public
   $ git init
   $ git remote add origin git@github.com:<github-username>/bookshelf.git
   

Là, créez et checkout une nouvelle branche `gh-pages`.

   $ git checkout -b gh-pages
   Switched to a new branch 'gh-pages'
   

Et ajoutez tous les fichiers (dans `bookshelf/public`) à l’index, committez-les et poussez les modifications vers GitHub.

   $ git add --all
   $ git commit -m "bookshelf added"
   $ git push -f origin gh-pages
   

En quelques minutes, votre site web sera live sur `https://<github-username>.github.io/bookshelf/`.

À tout moment, vous pouvez régénérer votre site avec :

   $ (cd ..; hugo --theme=hugo_theme_robust)
   $ git add --all
   $ git commit -m "<some change message>"
   $ git push -f origin gh-pages
   

• * *

Ce guide de démarrage rapide a été initialement écrit par [Shekhar Gulati](https://twitter.com/shekhargulati) dans sa série de blog [52 Technologies in 2016](https://github.com/shekhargulati/52-technologies-in-2016).