TOC

Comment installer et utiliser Hugo, un générateur de site statique, sur Ubuntu 14.04

introduction

Hugo est un générateur de site statique rapide et facile à utiliser, écrit en Go et disponible sur plusieurs plates-formes. Les générateurs de sites statiques constituent un excellent choix pour les blogs et autres contenus ne nécessitant pas de contenu dynamique extrait d'une base de données. Des choix tels que Hugo vous permettent de simplifier votre pile, d’écrire de manière conviviale et de gérer les mises à jour et le contenu personnalisé sans avoir besoin du fardeau d’une solution de gestion de contenu complète.

Dans ce guide, nous expliquerons comment installer et utiliser Hugo sur un serveur Ubuntu 14.04. Cela nous permettra de configurer un site statique, de créer du contenu et de publier sur le même serveur ou de le déployer sur un site de production.

Conditions préalables

Pour suivre ce guide, vous devez avoir accès à un serveur Ubuntu 14.04. Sur ce serveur, vous devrez avoir un utilisateur non root avec les privilègessudo configuré pour effectuer des tâches administratives. Vous pouvez découvrir comment créer un utilisateursudo en suivant nosUbuntu 14.04 initial server setup guide.

Installer la dernière version de Hugo

Hugo n’est pas disponible dans les dépôts par défaut d’Ubuntu. Cependant, des packages sont disponibles sur GitHub pour diverses architectures et distributions.

Trouvez votre architecture système

Avant de commencer, nous devrions vérifier l’architecture de notre machine Ubuntu afin de pouvoir télécharger le bon paquet. Sur votre serveur, tapez: 

uname -i

Si vous voyez ce qui suit, vous exécutez une installation64-bit d'Ubuntu: 

Outputx86_64

Si, à la place, votre sortie ressemble à ceci, cela signifie que vous travaillez avec la version32-bit d'Ubuntu: 

Outputi686

Nous utiliserons ces informations ci-dessous.

Téléchargez et installez le package Hugo

Visitez leHugo releases page pour trouver la dernière version stable d'Hugo (la plus proche du haut). Si vous faites défiler le texte d’annonce de la fonctionnalité, vous devriez trouver une section intitulée «Téléchargements».

Ensuite, nous devons copier l’emplacement du lien pour le package d’installation approprié. Le package correct dépendra de l'architecture de serveur que vous avez trouvée ci-dessus.

  • Si vous êtes sur un64-bit version of Ubuntu, faites un clic droit sur le lien se terminant paramd64.deb et copiez l'emplacement du lien.

  • Si vous êtes sur un32-bit version of Ubuntu, faites un clic droit sur le lien se terminant pari386.deb et copiez l'emplacement du lien.

Sur votre serveur, connecté en tant qu'utilisateur avec les privilègessudo, déplacez-vous dans un répertoire dans lequel vous disposez d'une autorisation d'écriture. Utilisez la commandewget et collez l'emplacement du lien que vous avez copié pour télécharger Hugo: 

cd ~
wget https://github.com/spf13/hugo/releases/download/v0.14/hugo_0.14_amd64.deb

Maintenant, vous pouvez installer le package avecdpkg en tapant: 

sudo dpkg -i hugo*.deb

Testez le succès de l'installation en demandant à Hugo d'imprimer sa version du logiciel: 

hugo version

Hugo devrait imprimer sa version actuelle du logiciel: 

OutputHugo Static Site Generator v0.14 BuildDate: 2015-05-25T21:29:16-04:00

Installation du logiciel de support Hugo

L'application principale Hugo devrait maintenant être installée. Cependant, il y a quelques logiciels supplémentaires que nous devrions installer pour nous aider à être opérationnels.

Installer les thèmes Hugo

Le paquet principal Hugo n'inclut aucun thème. Les thèmes Hugo définissent le rendu du contenu du site pour les utilisateurs. Le moyen le plus simple d'obtenir des thèmes Hugo est de cloner le référentiel Hugo themesgit, qui fournit de nombreux thèmes préconfigurés. Nous devrons installergit pour ce processus.

Nous pouvons trouvergit dans les référentiels par défaut d'Ubuntu. Mettez à jour l'index du package local, puis installezgit en tapant: 

sudo apt-get update
sudo apt-get install git

Ensuite, nous pouvons cloner le référentiel de thèmes Hugo. Le référentiel sur GitHub est organisé avec chaque thème individuel inclus en tant que sous-module.

Comme les sous-modules compliqueraient considérablement le contrôle de version du contenu réel de notre site, nous allons simplement cloner les thèmes dans notre répertoire personnel. Nous pouvons ensuite créer un lien symbolique vers les thèmes de notre répertoire de sites. Cela nous permettra également de partager facilement le répertoire de thèmes si nous avons plusieurs sites.

Clonez le référentiel de thèmes dans votre répertoire personnel en tapant: 

git clone --recursive https://github.com/spf13/hugoThemes ~/themes

Installer le surligneur de syntaxe Pygments

Nous allons également installer un logiciel Python appelé Pygments. Ceci fournit une logique de coloration syntaxique côté serveur pour tous les blocs de code qui seraient inclus dans nos pages rendues. Nous pouvons installer Pygments facilement avecpip, le gestionnaire de paquets de Python.

Nous pouvons obtenirpip à partir des référentiels par défaut en tapant: 

sudo apt-get install python-pip

Une foisapt terminé, nous pouvons utiliserpip pour installer lesPygments en tapant: 

sudo pip install Pygments

Cela nous permettra d'inclure des blocs de code à la syntaxe surlignée prenant en charge plus de 300 langues dans notre contenu de publication, si nous le souhaitons. Vous pouvez en savoir plus sur lesproject’s page.

Activer la complétion automatique de Hugo Bash

Une dernière chose que nous allons faire avant de commencer à travailler sur notre premier site est de générer les fonctions de saisie semi-automatique de Hugobash. Nous pouvons le faire en tapant: 

sudo hugo gen autocomplete

Ensuite, nous pouvons utiliser la configuration de complétion à l’échelle du système pour que notre shell actuel puisse utiliser les fonctions de saisie semi-automatique sans se déconnecter et se reconnecter: 

. /etc/bash_completion

Maintenant, si vous tapezhugo suivi de quelques tapotements de la touche TAB, vous verrez les commandes que Hugo connaît: 

hugo [TAB][TAB][TAB]
Outputbenchmark        config           gen  help             new              undraft
check            convert          gendoc           list             server           version

Créer votre premier site

Maintenant que nous sommes tous installés, nous pouvons créer notre premier site Hugo. Hugo a un générateur qui peut créer un squelette des fichiers et des répertoires nécessaires à son fonctionnement.

Nous pouvons créer un nouveau site dans votre répertoire personnel en tapant: 

hugo new site ~/my-website

Déplacez-vous sur votre nouveau site Hugo et jetez un coup d'œil autour de vous: 

cd ~/my-website
ls -F

Vous verrez la structure des répertoires et le fichier de configuration principal utilisé pour construire le site Hugo: 

Outputarchetypes/  config.toml  content/  data/  layouts/  public/  static/

Allons-y et lions le répertoire~/themes que nous avons cloné dans notre nouveau site. Afin de rendre ce lien plus flexible pour un déploiement possible, nous allons créer un lien symbolique relatif. Si vous déployez votre référentiel Hugo sur un serveur distant, vous devrez simplement vous assurer de cloner à nouveau le répertoire themes dans le répertoire parent de Hugo: 

ln -s ../themes .
ls -l
Outputtotal 28
drwxrwxr-x  2 demouser demouser 4096 Nov  5 11:25 archetypes
-rw-rw-r--  1 demouser demouser  210 Nov  5 11:55 config.toml
drwxrwxr-x  3 demouser demouser 4096 Nov  5 11:38 content
drwxrwxr-x  2 demouser demouser 4096 Nov  5 11:25 data
drwxrwxr-x  2 demouser demouser 4096 Nov  5 11:25 layouts
drwxrwxr-x 13 demouser demouser 4096 Nov  5 11:25 public
drwxrwxr-x  2 demouser demouser 4096 Nov  5 11:25 static
lrwxrwxrwx  1 demouser demouser    9 Nov  5 14:21 themes -> ../themes

Comme vous pouvez le voir ci-dessus, le répertoire themes de notre répertoire actuel est en fait un lien vers le référentiel de thèmes que nous avons cloné dans notre répertoire home.

Valider votre site pour le contrôle de source

Avant de configurer nos paramètres et de créer du contenu, nous devons transformer notre nouveau site en référentiel Git.

Assurez-vous que vous êtes dans le répertoire de votre site et initialisez un nouveau référentielget en tapant: 

cd ~/my-website
git init
OutputInitialized empty Git repository in /home/demouser/my-website/.git/

Ensuite, configurez les éléments de configuration de base degit nécessaires pour valider le code dans un référentiel. La manière la plus simple de le faire est d'utiliser la commandegit config --global. Nous devons définir notre nom et notre adresse e-mail afin quegit puisse enregistrer correctement nos informations en tant que committer: 

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Par défaut,git ne validera aucun répertoire vide dans le référentiel. Hugo exige parfois que ces répertoires soient présents même s’ils ne contiennent aucun contenu. Pour contourner ce problème, nous pouvons inclure un fichier.gitkeep caché dans chacun de ces répertoires vides. Cela suffit àgit pour valider le répertoire sans affecter la fonctionnalité réelle d'Hugo.

Nous pouvons ajouter un fichier caché.gitkeep à chacun de nos répertoires de niveau supérieur (autre que le répertoire caché réel.git) en tapant: 

for DIR in `ls -p | grep /`; do touch ${DIR}.gitkeep; done

Nous pouvons voir qu'un fichier caché.gitkeep a été ajouté à tous nos répertoires de niveau supérieur en tapant: 

find . -name .gitkeep
Output./data/.gitkeep
./layouts/.gitkeep
./archetypes/.gitkeep
./static/.gitkeep
./content/.gitkeep

Nous voulons également nous assurer que le contenu de notre site rendu estnot ajouté au contrôle de code source. Les ressources HTML, JavaScript et CSS réelles doivent être générées à chaque déploiement, et non conservées dans le contrôle de source lui-même. Nous pouvons dire àgit d'ignorer le répertoirepublic où le contenu généré serait stocké en ajoutant cet emplacement à un fichier.gitignore: 

echo "public" >> .gitignore

Maintenant, nous pouvons engager notre squelette de site propre dans le référentiel en ajoutant tout le contenu du répertoire actuel, puis en validant: 

git add .
git commit -m 'Initial commit, pre-configuration.'

Réglage de la configuration initiale de votre site

Réglons le fichier de configuration principal de Hugo pour configurer la manière dont Hugo construira notre site.

Ouvrez le fichierconfig.toml dans votre éditeur: 

nano config.toml

À l'intérieur, vous trouverez quelques éléments que nous devons ajuster:

~/my-website/config.toml

baseurl = "http://replace-this-with-your-hugo-site.com/"
languageCode = "en-us"
title = "My New Hugo Site"

Comme l'indique le suffixe de fichier, ce fichier est écrit en utilisant lesTOML language. C'est un langage de configuration simple qui utilise principalement des clés, des valeurs et des sections.

Le premier élément que nous devrions modifier est l'élémentbaseurl. Ceci est utilisé pour construire des URL lors de la construction du site. Changez-le pour référencer le nom de domaine ou l'adresse IP publique de votre serveur. Vous devez également modifier la valeur attribuée auxtitle. Ceci est utilisé pour définir le titre de l'onglet ou de la fenêtre pour votre site et est utilisé sur la page pour certains thèmes:

~/my-website/config.toml

baseurl = "http://your_domain_or_IP/"
languageCode = "en-us"
title = "Your Site Name"

Il y a quelques paramètres supplémentaires que nous devrions ajouter à ce fichier. Premièrement, nous pouvons définir notre éditeur de texte préféré. Ainsi, lorsque nous générerons de nouvelles pages, le modèle de page sera ouvert dans notre éditeur, prêt à fonctionner.

Nous devrions également définir un thème par défaut. Nous allons utiliser un thème appelé «nofancy» pour commencer. Vous pouvez le remplacer ultérieurement sur la ligne de commande pour tester des alternatives, puis modifier le fichier de configuration lorsque vous en trouverez un qui vous convient. Nous allons également définir notre style de bloc de code préféré:

~/my-website/config.toml

baseurl = "http://your_domain_or_IP/"
languageCode = "en-us"
title = "Your Site Name"
newContentEditor = "nano"
theme = "nofancy"
pygmentsStyle = "native"

Vous pouvez trouver plus d'informations sur les paramètres disponibles surthis page. Pour l'instant, enregistrez et fermez le fichier.

Commetons nos modifications de configuration avant de continuer: 

git add .
git commit -m 'Initial configuration complete'

Création de nouvelles pages pour votre site

Nous sommes maintenant prêts à commencer à créer le contenu du site. Le contenu dans Hugo est écrit en utilisant des langages de balisage faciles à utiliser. Les métadonnées de page sont fournies dans une section spéciale de chaque page appelée "avant-propos" en utilisant les mêmes syntaxes de configuration disponibles pour le fichier de configuration principal.

Nous pouvons générer du nouveau contenu avec Hugo en utilisant la commandehugo new suivie du chemin vers le contenu que nous voulons produire. Par défaut, le contenu Hugo est écrit dans Markdown. Pour qu'Hugo génère correctement du HTML à partir de nos pages Markdown, nous devons créer des fichiers qui se terminent par l'extension.md.

Créer une page à propos

Les pages qui seront liées à partir de la page d'accueil et les chemins relatifs dont vos pages auront besoin sont en grande partie dictés par votre thème. Consultez la page du thème sur GitHub pour en savoir plus sur ses attentes. Notre thème "nofancy" contient un lien pour une page "à propos de". Commençons par créer cette page: 

hugo new about.md

Une nouvelle page sera créée dans le répertoirecontent appeléabout.md. Puisque nous avons défini l'optionnewContentEditor dans notre fichier de configuration, le fichier devrait être automatiquement ouvert avec votre éditeur préféré. Cela devrait ressembler à ceci pour commencer:

~/my-website/content/about.md

+++
categories = ["misc"]
date = "2015-11-05T16:58:58-05:00"
title = "about"

+++

Les paramètres et les métadonnées de la page sont configurés dans la «page d'accueil» de la page, la section délimitée de chaque côté par des lignes de «+». La matière incluse par défaut est souvent définie par le thème que vous utilisez.

Notre thème actuel comprend trois éléments dans l'avant-propos des pages générées. Vous pouvez les ajuster ou ajouter des éléments supplémentaires comme vous le souhaitez. Les variables générales disponibles pour Hugo peuvent être trouvéeshere. Le thème que vous avez choisi peut également utiliser ses propres variables d’avant-propos. Consultez le fichier README de votre thème dans lesHugo theme repository pour obtenir des détails sur votre thème.

Voici quelques éléments importants d’avant-propos:

  • date: la date à utiliser pour trier votre contenu

  • description: une description du contenu de la page

  • draft: marquera la page comme non prête pour la publication si elle est définie sur true

  • slug: définissez ceci si vous souhaitez spécifier un autre nom d'URL pour le contenu

  • publishdate: cela peut être défini sur une date ultérieure si vous ne souhaitez créer la page qu'après une certaine date

  • title: le titre de votre page

Pour l’instant, modifions simplement le titre de notre page «À propos de»:

~/my-website/content/about.md

+++
categories = ["misc"]
date = "2015-11-05T16:58:58-05:00"
title = "About Me"

+++

Maintenant, nous pouvons ajouter du texte Markdown sous le "+" du bas. Cela sera traduit dans le corps du texte HTML. Nous ajouterons quelques paragraphes, un titre et une image sousCreative Commons mis à disposition depuisEva Hejda que nous avons aimé:

~/my-website/content/about.md

+++
categories = ["misc"]
date = "2015-11-05T16:58:58-05:00"
title = "About Me"

+++

Hello and welcome to my site!

## A Bit About Me

I like alpacas and I'm a fan of static sites.

![Great alpaca picture](https://upload.wikimedia.org/wikipedia/commons/c/c4/Alpaka_33444.jpg)

Lorsque vous avez terminé, enregistrez et fermez le fichier.

Créez votre premier post

Nous avons créé la pageabout.md à la racine de notre répertoire de contenu car c'est là que notre thème s'attend à ce qu'elle soit. Cependant, la plupart de nos articles seront mieux conservés dans un sous-répertoirepost (certains thèmes recherchent plutôt des articles dans un sous-répertoireposts).

Créons un premier article dans le répertoire "posts". Hugo créera automatiquement tous les principaux répertoires dont il aura besoin lors de la génération de pages: 

hugo new post/My-First-Post.md

Si nous utilisons des tirets dans le nom de fichier Markdown, ils seront convertis en espaces pour le titre rempli automatiquement:

~/my-website/content/post/My-First-Post.md

+++
categories = ["misc"]
date = "2015-11-05T17:52:41-05:00"
title = "My First Post"

+++

Renseignez les métadonnées manquantes et ajoutez un abaissement à la page. Nous allons ajouter un exemple de code ici afin que vous puissiez voir le code soulignant que fournit l'outil Pygments. Pour ce faire, au lieu d’utiliser un triple backtick Markdown classique pour entourer un bloc de code, nous plaçons le code entre deux balises de surbrillance qui ressemblent à ceci: 

{{< highlight language >}}

code_goes_here

{{< /highlight >}}

Cela appliquera le style Pygment au code à l'intérieur. Gardez à l'esprit que certains thèmes incluent des fichiers CSS qui remplaceront les choix de style de Pygment. La balise<pre> a souvent un style supplémentaire qui peut remplacer la couleur d'arrière-plan du thème Pygment. Notre thème particulier ne souffre pas de ce problème cependant.

Dans notre page, le contenu complet ressemblera à ceci:

~/my-website/content/post/My-First-Post.md

+++
categories = ["misc"]
date = "2015-11-05T17:52:41-05:00"
title = "My First Post"

+++

This is my first post on the site.  I hope that you like it!

## Welcome Function

Here is a little Python function to welcome you:

{{< highlight python >}}
def hello_world():
    print "Hello there!"
{{< /highlight >}}

Enregistrez et fermez le fichier lorsque vous avez terminé. Si vous avez besoin d'éditer ces pages plus tard, vous pouvez les trouver dans le répertoirecontent de votre site Hugo.

Commençons nos nouvelles pages dans notre référentielgit: 

git add .
git commit -m 'First pages of our site'

Construire et servir le site

Hugo peut prendre vos fichiers Markdown, appliquer les paramètres définis dans votre configuration et votre thème et restituer les pages HTML réelles qui seront affichées aux visiteurs.

Pour construire votre site, vous pouvez simplement taper: 

hugo

Cela générera vos pages et placera tout le contenu rendu dans le répertoirepublic sur votre serveur. Si vous le souhaitez, vous pouvez transférer le contenu de ce répertoire sur votre serveur Web pour déployer et servir votre contenu.

Note

[.note] # Hugo ne nettoie pas le répertoire de sortie après chaque compilation. Cela signifie qu'il est possible que du contenu périmé soit laissé dans le répertoirepublic d'une version précédente. Les développeurs Hugo vous recommandent de supprimer le répertoirepublic après chaque build (surtout avant de passer à la production) afin que tout le contenu puisse être recréé à neuf.
#

Hugo comprend également son propre serveur Web. Bien que vous ne souhaitiez peut-être pas l'utiliser pour desservir votre trafic de production, il s'agit d'un excellent moyen d'afficher vos copies de travail et de tester le rendu avant de déployer vos pages.

Pour rendre vos pages disponibles sur votre serveur Hugo, utilisez la commandehugo server. Cela rendra vos pages (il n'est pas nécessaire d'exécuter la commandehugo au préalable), puis démarre le serveur Web.

Nous utiliserons l'option--bind pour spécifier que nous souhaitons rendre le site disponible sur toutes les interfaces (si vous avez installé Hugo localement, vous pouvez le supprimer). Nous devons également inclure l'option--bindUrl. Nous définissons cela dans notre fichier de configuration, mais cela n’a pas été repris par le serveur dans la version actuelle de Hugo. Définissez ceci sur le nom de domaine ou l'adresse IP de votre site Web: 

rm -r public
hugo server --bind=0.0.0.0 --baseUrl=http://your_domain_or_IP/

Si vous définissezdraft = true dans l'une de vos pages, ou définissez lesdate sur une heure future dans certains de vos contenus, vous pouvez créer et prévisualiser ces pages en incluant les-D et-F respectivement: 

rm -r public
hugo server --bind=0.0.0.0 --baseUrl=http://your_domain_or_IP/ -D -F

Désormais, si vous visitez le nom de domaine ou l'adresse IP de votre serveur dans votre navigateur Web et que vous ajoutez la spécification de port:1313 à la fin, vous verrez votre site rendu: 

http://your_domain_or_IP:1313

Hugo test site

Nous pouvons cliquer sur notre premier message pour consulter notre Markdown rendu. Notre style Pygments a été appliqué au bloc de code:

Hugo first page

Si nous cliquons sur le lien «À propos de», nous serons redirigés vers notre page «À propos de moi:

Hugo about page

Comme vous pouvez le constater, notre thème est assez basique mais il fonctionne exactement comme prévu.

Si vous souhaitez essayer des thèmes alternatifs, vous pouvez ajouter l'option--theme= à la fin de votre ligne de serveur: 

rm -r public
hugo server --bind=0.0.0.0 --baseUrl=http://your_domain_or_IP/ --theme=redlounge

N'oubliez pas que chaque thème a ses propres attentes concernant la structure de votre répertoire et vos paramètres de configuration. Vous devrez peut-être ajuster certaines choses pour que chaque nouveau thème fonctionne correctement.

Si vous souhaitez utiliser Hugo pour servir du contenu sur le port 80 comme un serveur Web conventionnel, vous devrez ajouter l'option--port à votre ligne de commande. Vous devrez également ajoutersudo à la commande car les ports inférieurs à 1024 sont restreints pour les utilisateurs normaux: 

rm -r public
sudo hugo server --bind=0.0.0.0 --baseUrl=http://your_domain_or_IP/ --theme=redlounge --port=80

Vous devriez maintenant pouvoir visiter votre site dans une fenêtre de navigateur sans le numéro de port ajouté.

Après avoir exécuté le serveur Hugo avecsudo, vous devrez également faire précéder la commanderm avecsudo: 

sudo rm -r public

Conclusion

Hugo est un excellent moyen de faire sortir un site rapidement et facilement. Les sites statiques offrent une alternative moins gourmande en ressources aux sites CMS traditionnels. La majorité des utilisateurs n'ont pas besoin de contenu basé sur une base de données et n'utilisent pas les fonctionnalités supplémentaires fournies par les systèmes de gestion de contenu. Avec Hugo, vous pouvez concentrer votre énergie sur la création de contenu plutôt que sur l'administration d'un système complexe.

Nosnext guide iront plus loin dans cette configuration en expliquant comment déployer un site Hugo à l'aide de Git Hooks.

Related