QuickStart

Dans ce guide de démarrage, nous allons construire une bibliothèque qui listera des livres et leurs critiques.

Étape 1. Installez Hugo

Installez Hugo. Si vous installez à partir des Versions Hugo, vous devrez sauvegarder l’exécutable principal sous hugo(ou hugo.exe sur Windows) quelque part dans votre PATH. Vous aurez besoin de la commande hugopour les étapes suivantes.

Une fois hugo intallé, assurez-vous de lancer la commande help pour vérifier l’installation de hugo. Ci-dessous, vous pouvez voir une partie traduite de l’output de la 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/.

Vous pouvez vérifier la version de hugo en utilisant la commande en dessous.

$ hugo version

Hugo Static Site Generator v0.25 darwin/amd64 BuildDate: 2017-07-07T19:09:03+02:00

Étape 2. Échafaudez le site de la Bibliothèque avec Hugo

Hugo dispose de commmandes qui nous permettent d’échafauder rapidement un site web géré avec Hugo. Naviguez vers un endroit qui vous plaira sur votre système de fichiers, et créez un nouveau site bibliotheque en exécutant la commande qui suit :

$ hugo new site bibliotheque

Changez de répertoire vers le nouveau répertoire bibliotheque

$ cd bibliotheque 

Lancez la commande tree -a pour visualiser le contenu de votre répertoire :

$ tree -a

.
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

6 directories, 1 file

Vous verrez le dossier bibliotheque qui comprend 6 sous-dossiers et 2 fichiers. Jetons un oeil à chacun d’eux.

• archetypes : [Archetypes][archetypes] vous permet de pré-configurer le front-matter pour les fichiers de contenu dans Hugo pour un meilleur échafaudage du contenu en utilisant la commande hugo new.
• config.toml : Hugo utilise .tomlpour son propre format de configuration. mais il accepte aussi bien les formats .yml ou .json. Les réglages de configuration mentionnés dans le fichier config.tomls’appliquent à l’ensemble du site web et comprennent des variables globales importantes telles que la baseURL et le title de votre site web. (Voir configuration)
• content : Ce dossier unique abrite tous les contenus de votre site web. Chaque sous-répertoire dans content s’appelle une section. Si votre site web dispose de sections pour les articles, événements et tutoriels, vous pourriez créer content/posts, content/events et content/tutoriels.
• data : Ce dossier est utilisé pour stocker les fichiers de données en séries (YAML, JSON, ou TOML) qui peuvent être utilisés dans les data templates et votre menu de site web.
• layouts : C’est le carrefour pour tous vos modèles, incluant les modèles de listes et sections et shortcodes.
• static : Ce dossier accueille tout le contenu statique ; par exemple les images, JavaScript et CSS. Tout ce qui est dans /static est copié tel quel vers votre site web fini.
• themes : C’est l’endroit où vous stockerez les thèmes Hugo. Vous pouvez voir une galrie de tous les thèmes sur http://themes.gohugo.io

Étape 3. Ajoutez du Contenu

Ajoutons maintenant un article à notre bibliotheque. Nous utiliserons la commande hugo new pour ajouter un article. Ce premier post sera sur le livre Good To Great. Assurez-vous de bien être dans le dossier bibliotheque. Et lancez la commande :

    $ hugo new post/good-to-great.md

/Users/votrenomutilisateur/bibliotheque/content/post/good-to-great.md created

La commande au-dessus créera un nouveau dossier post à l’intérieur du dossier content et créera content/post/good-to-great.md. Le répertoire pour votre projet Hugo ressemblera maintenant à ce qui suit :

.
├── archetypes
├── config.toml
├── content
│   └── post
│       └── good-to-great.md
├── data
├── layouts
├── static
└── themes

Ouvrez good-to-great.md dans votre éditeur de texte préféré :

+++
date = "2017-02-19T21:09:05-06:00"
title = "good to great"
draft = true

+++

Le contenu encadré entre les signes +++ est le front matter pour le contenu. Le front matter vous permet de définir des méta-données embarquées qui voyage avec le fichier de contenu. Parce que nous n’avons pas configuré quelque archétype pour notre projet, Hugo a utilisé ses propriétés de configuration natives, qui incluent les trois valeurs dans le front-matter :

• date spécifie la date et l’horaire à laquelle le billet a été créé.
• title spécifie le titre du billet.
• draft quand il est réglé sur true, dit à Hugo que ce post n’est pas prêt pour la publication.

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"
+++

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.

Étape 4. Servez le contenu

Hugo a un serveur intégré qui peut servir le contenu de votre site web afin que vous puissiez le prévisualiser facilement et développer. Pour servir le contenu, lancez la commande suivante à l’intérieur de votre répertoire bibliotheque :

$ hugo server

Vous devriez voir quelque chose de similaire à ce qui suit :

Built site for language en:
0 of 1 draft rendered
0 future content
0 expired content
0 regular pages created
1 other pages created
0 non-page files copied
0 paginator pages created
0 tags created
0 categories created
total in 1 ms
Watching for changes in /Users/yourusername/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

Cette commande lancera le serveur sur le port 1313. Vous pourrez regarder votre blog à l’adresse http://localhost:1313/. Cependant, si vous allez sur le lien, vous ne verrez rien ! Deux raisons à cela :

1. Comme vous pouvez le voir dans la sortie de commande hugo server, Hugo n’a pas produit le draft. Hugo ne produira les drafts (ébauches) que si vous passez l’option buildDrafts sur la commande hugo server.
2. Nous n’avons pas spécifié comment le contenu Markdown devrait être produit. Nous devons spécifier un thème à utiliser par Hugo. Nous ferons ça à l’étape suivante.

Tuez le serveur en utilisant Ctrl + C et relancez le serveur avec l’option --buildDrafts ajoutée à la commande :

hugo server --buildDrafts

Vous devriez maintenant voir quelque chose de similaire à ce qui suit :

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
0 paginator pages created
0 tags created
0 categories created
total in 2 ms
Watching for changes in /Users/yourusername/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

Très bien. Maintenant nous avons notre page unique “build”, mais nous ne voyons rien dans le navigateur à l’adresse http://localhost:1313/. Ceci n’était fait que pour démontrer l’utilité de l’option --buildDrafts.

Pendant que nous nous approchons du but, nous devons indiquer à Hugo un thème à utiliser au moment de la construction du site.

Étape 5. Ajoutez un thème

Les thèmes fournissent à Hugo la mise en page et les modèles pour rendre votre site Web. Vous pouvez voir la sélection complète de thèmes open source sur https://themes.gohugo.io/.

Les thèmes doivent être ajoutés dans le dossier themes, l’un des dossiers échafaudés avec la commande hugo new site que nous avons utilisée pour démarrer notre projet Hugo. Pour installer nos thèmes, déplaçons-nous tout d’abord dans le répertoire themes :

$ cd themes

Vous pouvez cloner un ou plusieurs thèmes à l’intérieur de votre dossier themes. Nous utiliserons le thème robust, mais au commit le plus récent à la dernière mise à jour de ce guide de démarrage rapide.

Une fois dans le dossier themes, vous pouvez uitliser la commande suivante en une ligne pour cloner Robust, check out le commit spécifique, et revenir ensuite à la racine de votre dossier projet :

git clone https://github.com/dim0627/hugo_theme_robust.git && cd hugo_theme_robust && git checkout 3baae29 && cd ../..

Maintenant redémarrons le serveur Hugo mais avec l’ajout de l’option --theme pour Robust :

hugo server --theme=hugo_theme_robust --buildDrafts

Vous devriez voir un output de console similaire à ce qui suit :

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 8 ms
Watching for changes in /Users/yourusername/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

Si Hugo ne trouve pas le thème spécifié dans le dossier themes, il lancera une exception comme affiché en-dessous._

FATAL: 2016/02/14 Unable to find theme Directory: /Users/xtof/bibliotheque/themes/robust

Pour voir votre site web, rendez-vous maintenant sur http://localhost:1313/. Vous verrez ce qui s’affiche ci-dessous.

Comme nous l’avions fait lors de l’échafaudage de notre nouveau site web Hugo, jetons un oeil à ce que comprend un thème typique. Ce qui suit n’est qu’une sélection de ce que vous verriez si vous listiez les contenus du répertoire du thème Robust. Il y a aussi quelques-uns des fichiers par défaut créés par Hugo v0.23. (Voir Créer un Thème)

.
├── LICENSE.md
├── archetypes
│   └── default.md
├── layouts
│   ├── 404.html
│   ├── _default
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   └── partials
│       ├── footer.html
│       └── header.html
├── static
│   ├── css
│   └── js
└── theme.toml

• theme.toml est le fichier de configuration du thème qui vous donne l’information sur le thème comme le nom et la description du thème, les détails de l’auteur, la licence du thème, la version minimum d’Hugo qui sera par défaut celle de votre version d’Hugo localement installée.
• layouts contient différentes vues (c.a.d. des modèles pour différents types de contenus. Dans ce guide de démarrage, nous voyons que chaque type de contenu a un fichier single.html et un fichier list.html. single.html est utilisé pour rendre un élement unique de contenu. list.html s’utilise pour visualiser *.md* dans la section posts. Pensez à list.html comme exemple.com/posts/ et single.html comme exemple.com/posts/mon-post-unique/.
• static a le même objectif que celui du static dans notre échafaudage original. Ce dossier stocke tous les actifs statiques utilisés par le thème et il est copié tel quel au moment du build.

Étape 6. Utilisez plusieurs thèmes

Vous pouvez facilement tester différentes configurations en alternant entre différents thèmes. dans Hugo. Supposons que nous voulions essayer le thème bleak.. Tuez le serveur Hugo si vous êtes encore en train de le faire fonctionner à la ligne de commande.

À partir de la racine de votre projet, vous pouvez utiliser cette commande-en-une-ligne pour vous déplacer dans le dossier themes, cloner Bleak et revenir à la racine de votre projet :

cd themes && git clone https://github.com/Zenithar/hugo-theme-bleak.git && cd ..

Maintenant, redémarrez le serveur avec notre option de nouveau thème :

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

Notre site web utilise maintenant le thème bleak sur http://localhost:1313 et s’affiche différemment comme ci-dessous :

Étape 7. Mise à jour de votre configuration

Arrêtez si besoin le serveur et redémarrez avec le thème robust, car nous allons utiliser ce thème pour ce guide de démarrage rapide :

hugo server --theme=hugo_theme_robust --buildDrafts

Mise à jour de Notre config.toml

Notre site web utilise actuellement les valeurs stupides spécifiées dans le fichier de configuration bibliotheque/config.toml, qui a été auto-généré avec hugo new site bibliotheque. Mettons à jour la configuration.

baseURL = "http://exemple.org/"
languageCode = "fr-fr"
title = "Critiques de Livres par Shekhar Gulati"

[Params]
      Author = "Shekhar Gulati"

Regardez votre Site se Recharger Instantanément

Hugo supporte nativement le rechargement en live. Ce qui veut dire que Hugo reconstruira et rechargera votre site à chaque fois que vous sauvegarderez une modification d’un contenu, template, asset statique et même votre fichier de configuration. Vous devriez voir quelque chose de similaire à la capture-écran en-dessous en vous rendant sur http://localhost:1313 une fois que vous aurez sauvegardé les modifications ci-dessus dans votre fichier config.toml :

Outre la visualisation, vous retrouverez la modification dans la console. Dès que vous avez modifié le fichier de configuration, Hugo a appliqué ces modifications aux pages concernées et reconstruit le site :

Config file changed: /Users/votrenomutilisateur/bibliotheque/config.toml
Started building sites ...
Built site for language en
1 of 1 draft rendered
0 future content
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 20 ms

Étape 8. Personnalisez le Thème robust

Le thème robust est un bon départ pour notre bibliothèque en ligne mais nous voulons le personnaliser afin de le rapprocher de nos besoins pour une bibliothèque. Hugo facilite la personnalisation des thèmes. Vous pouvez aussi créer vos propres thèmes. Pour ce guide nous nous concentrerons sur la personnalisation.

Le premier changement sera d’utiliser une image par défaut différente de celle utilisée dans le thème. L’image par défaut du thème utilisée à la fois dans le fichier list.htmlet single.html se trouve à l’intérieur de themes/hugo_theme_robust/static/images/default.jpg. Nous pouvons facilement l’annuler en créant une simple structure de dossier à l’intérieur de notre dossier static.

Créez un dossier images dans le répertoire bibliotheque/static et copiez dedans une image avec le nom default.jpg. Nous utiliserons par défaut l’image affichée en dessous.

Hugo synchronisera les modifications et rechargera le site web pour utiliser cette nouvelle image

Maintenant, nous devons modifier le layout de la page index afin que seules les images soient affichées au lieu du texte. Le fichier themes/hugo-theme_robust/layouts/index.html fait référence au partiel li qui produit la vue en liste ci-dessous.

<article class="li">
  <a href="{{ .Permalink }}" class="clearfix">
    <div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
    <div class="detail">
      <time>{{ with .Site.Params.DateForm }}{{ $.Date.Format . }}{{ else }}{{ $.Date.Format "Mon, Jan 2, 2006" }}{{ end }}</time>
      <h2 class="title">{{ .Title }}</h2>
      <div class="summary">{{ .Summary }}</div>
    </div>
  </a>
</article>

Créez un nouveau fichier li.html à l’intérieur du dossier bibliotheque/layouts/_default. Si vous êtes à la racine de votre projet, vous pouvez utiliser la commande-en-une-ligne qui suit pour créer à la fois le fichier et revenir à la racine :

cd layouts && mkdir _default && cd _default && touch li.html && cd ../..

Copiez le contenu affiché en dessous dans le nouveau fichier li.html. Si vous comparez ça avec le li.htmllivré avec le thème Robust, vous remarquerez que nous avons enlevé les détails du livre, afin que seule l’image s’affiche.

<article class="li">
  <a href="{{ .Permalink }}" class="clearfix">
    <div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
  </a>
</article>

Maintenant, le site web devrait ressembler à ce qui s’affiche en-dessous

Ensuite, nous voulons retirer l’information présente en pied de page concernant le thème. Pour faire ainsi, créez un nouveau dossier sur bibliotheque/layouts/partials. Celui-ci détiendra notre nouveau fichier appelé default_foot.html

Ceci est un nouveau modèle partiel. Si vous êtes encore à la racine du répertoire de votre projet, vous pouvez utilisez la commande-en-une-ligne qui suit pour créer le partial avant de de revenir à la racine du projet :

cd layouts && mkdir partials && cd partials && touch default_foot.html && cd ../..

Ajoutez maintenant ce qui suit à notre nouveau modèle partiel default_foot.html :

<footer class="site">
  <p>{{ with .Site.Copyright | safeHTML }}{{ . }}{{ else }}&copy; {{ $.Site.LastChange.Year }} {{ if isset $.Site.Params "Author" }}{{ $.Site.Params.Author }}{{ else }}{{ .Site.Title }}{{ end }}{{ end }}</p>
  <p>Powered by <a href="http://gohugo.io" target="_blank">Hugo</a>,</p>
</footer>

A ce stade nous utilisons l’image par défaut mais nous aimerions utiliser l’image du livre que nous pourrions rattacher au livre. Chaque critique de livre définira un réglage de configuration dans son front matter. Mettez à jour le contenu et le front matter de good-to-great.md comme affiché ci-dessous :

+++
date = "2017-02-19T21:09:05-06:00"
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.

Piquez quelque part (légal SVP) une image, appelez-la good-to-great.jpg, et placez-la dans le dossier bibliotheque/static/images.

Après avoir ajouté quelques autres livres à notre bibliothèque, voici à quoi ressemble le premier rayon.

Étape 9. Rendez les posts publics

À ce stade, tous les posts que nous avons écrits sont en statut draft, c’est à dire draft=true (ébauche). Afin de faire qu’un draft soit public, vous pouvez soit lancer une commande ou modifier manuellement le statut draft dans le post en false. Hugo fournit une commande pratique appelée undraftpour faire ça :

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

Si nous vérifions le front matter de good-to-great.md après avoir lancé cette commande, nous remarquons que Hugo a écrit la modification du statut draft au fichier :

+++
date = "2017-02-19T22:42:53-06:00"
draft = false
title = "Good to Great Book Review"
image = "good-to-great.jpg"
+++

Maintenant, nous pouvons lancer le serveur sans l’option buildDrafts.

$ hugo server --theme=hugo_theme_robust

Étape 10. Construisez votre site Web

Pour générer un site web qui puisse être déployé vers GitHub Pages. nous avons besoin de modifier la ligne baseURL dans notre configuration comme suit :

baseURL = "https://<votre nomutilisateur GitHub>.github.io/bibliotheque/"

Puis lancez la commande suivante à partir du répertoire racine de votre projet Hugo :

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 bibliotheque/public est créé contenant la source du site web généré.

P.S. En passant, (si vous avez essayé), le site web n’est pas accessible proprement via le protocole file:///.

Étape 11. Et après ?

Bravo ! Votre nouveau répertoire public bibliothèque/ est un site web Hugo entièrement généré et déployable. Tous vos fichiers étant statiques, vous avez d’innombrables options d’hébergement. Votre nouvelle structure de répertoire et votre format de contenu simple vont améliorer grandement votre site web.

Voic ce que vous pourriez regardez ensuite :

1. Voir les options d’hébergement et de déploiement pour partager votre nouveau site web Hugo avec le monde.
2. Apprenez en plus sur la modélisation puissante d’Hugo pour personnaliser votre site web Hugo à vos besoins spécifiques et pour le faire grandir.
3. Visitez le Forum de discussion Hugo pour poser des questions, répondre aux questions et devenir un membre actif de la communauté Hugo.

(Option) Étape 12. Déployez le site bibliotheque sur GitHub pages

Lançons le contôle de version de votre bibliotheque :

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

Maintenant les repos Git sous bibliotheque/themes ne rentreront plus en conflit avec votre repo bibliotheque, et c’est aussi le cas pour un repo Git dans bibliotheque/public.

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

$ cd public
$ git init
$ git remote add origin git@github.com:<votre-nomutilisateur-github>/bibliotheque.git

Puis créez et checkout une nouvelle branche gh-pages

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

Ajoutez tous les fichiers (dans bibliotheque/public) à l’index, commitez-les, et poussez les modifications sur GitHub.

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

Dans quelques minutes, votre site web sera vivant sur https://<github-nomutilisateur>.github.io/bibliotheque/.

A 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 tutoriel rapide a été initialement écrit par Shekhar Gulati dans sa série de blog 52 Technologies in 2016.