DÉMARRAGE FONDAMENTAUX FUNDAMENTALS

Configurer Hugo

La structure des dossiers d’un site Web Hugo—ou plus précisément, l’organisation source des fichiers contenant le contenu du site web et ses modèles—fournit la plupart des informations de configuration dont Hugo a besoin pour générer un site web fini.

Hugo ayant pré-réglé les valeurs sensibles par défaut, de nombreux sites web n’auront pas besoin d’un tel fichier de configuration. Hugo a été conçu pour reconnaître certains modèles d’utilisation typiques.

Ordre de Recherche de Configuration

Similaire à l’ordre de recherche de modèle, Hugo a un ensemble de règles par défaut pour chercher un fichier de configuration à la racine du répertoire source de votre site web avec un comportement par défaut :

  1. ./config.toml
  2. ./config.yaml
  3. ./config.json

Dans votre fichier config, vous pouvez indiquer à Hugo comment vous souhaitez que votre site web soit rendu, contrôler les menus de votre site et définir arbitrairement des paramètres pour tout le site et spécifiques à votre projet.

Configuration YAML

Voici un exemple typique d’un fichier de configuration YAML. Notez que le document s’ouvre avec 3 traits d’union et se ferme avec 3 périodes. Les valeurs imbriquées dans les params: rempliront la variable .Site.Params à utiliser dans les modèles :

config.yml
---
baseURL: "https://votresite.exemple.com/"
title: "Mon Site Hugo"
footnoteReturnLinkContents: "↩"
permalinks:
  post: /:year/:month/:title/
params:
  Subtitle: "Hugo is Absurdly Fast!"
  AuthorName: "Jon Doe"
  GitHubUser: "spf13"
  ListOfFoo:
    - "foo1"
    - "foo2"
  SidebarRecentLimit: 5
...

Toutes les variables, YAML

Ce qui suit est une liste de variables définies-par-Hugo dans un fichier exemple YAML. Les valeurs fournies dans cet exemple représentent les valeurs par défaut utilisées par Hugo.

---
archetypeDir:               "archetypes"
# nom hôte (et chemin) vers la racine, par ex. http://spf13.com/
baseURL:                    ""
# inclut le contenu marqué comme draft
buildDrafts:                false
# inclut le contenu avec une publishdate dans le futur
buildFuture:                false
# inclut le contenu déjà expiré
buildExpired:               false
# activer pour produire toutes les URLS relatives au contenu racine. Notez que cela n'affecte pas les URLs absolues. Voir la page "Gestion URL"
relativeURLs:               false
canonifyURLs:               false
# config file (par défaut path/config.yaml|json|toml)
config:                     "config.toml"
contentDir:                 "content"
dataDir:                    "data"
defaultExtension:           "html"
defaultLayout:              "post"
# Les traductions manquantes iront par défaut vers cette langue de contenu
defaultContentLanguage:     "en"
# Rend la langue par défaut du contenu dans le sous-dossier, par ex. /en/. Le dossier racine / redirigera vers /en/
defaultContentLanguageInSubdir: false
disableLiveReload:          false
# Ne pas construire les fichiers RSS
disableRSS:                 false
# Ne pas construire le fichier Sitemap
disableSitemap:             false
# Active la fonctionnalité GitInfo
enableGitInfo:              false
# Construit le fichier robots.txt
enableRobotsTXT:            false
# Ne produit pas la page 404 
disable404:                 false
# Ne pas injecter le générateur de meta tag sur la page d'accueil
disableHugoGeneratorInject: false
# Vous permet de désactiver tous les types de page et ne rendra rien en rapport avec 'kind';
# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404"
disableKinds: []
# Ne produit pas le chemin/url en bas de casse
disablePathToLower:         false                   ""
# Active le support des émoticônes Emoji pour le contenu de la page ; voir emoji-cheat-sheet.com
enableEmoji:                false
# Affiche un placeholder au lieu de la valeur par défaut ou une chaîne vide si une traduction manque
enableMissingTranslationPlaceholders: false
footnoteAnchorPrefix:       ""
footnoteReturnLinkContents: ""
# google analytics tracking id
googleAnalytics:            ""
# si true, auto-detecte les langues Chinese/Japanese/Korean dans le contenu. (.Summary et .WordCount peuvent fonctionner proprement en CJKLanguage)
hasCJKLanguage:             false
languageCode:               ""
layoutDir:                  "layouts"
# Enable Logging
log:                        false
# Log File path (if set, logging enabled automatically)
logFile:                    ""
# "toml","yaml", or "json"
metaDataFormat:             "toml"
newContentEditor:           ""
# Don't sync permission mode of files
noChmod:                    false
# Don't sync modification time of files
noTimes:                    false
# Pagination
paginate:                   10
paginatePath:               "page"
# See "content-management/permalinks"
permalinks:
# Pluralize titles in lists using inflect
pluralizeListTitles:        true
# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu")
preserveTaxonomyNames:      false
# filesystem path to write files to
publishDir:                 "public"
# enables syntax guessing for code fences without specified language
pygmentsCodeFencesGuessSyntax: false
# color-codes for highlighting derived from this style
pygmentsStyle:              "monokai"
# true use pygments-css or false will color code directly
pygmentsUseClasses:         false
# maximum number of items in the RSS feed
rssLimit:                   15
# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info
SectionPagesMenu:           ""
# default sitemap configuration map
sitemap:
# filesystem path to read files relative from
source:                     ""
staticDir:                  "static"
# display memory and timing of different steps of the program
stepAnalysis:               false
# theme a utiliser (situe par defaut dans /themes/NOMTHEME/)
themesDir:                  "themes"
theme:                      ""
title:                      ""
# le guide de style pour la Casse du Titre pour la fonction title et autre mise en casse automatique du title dans Hugo.
// Le valeurs valides sont "AP" (par défaut), "Chicago" et "Go" (qui etait ce que vous aviez dans  Hugo <= 0.25.1).
// Voir https://www.apstylebook.com/ et http://www.chicagomanualofstyle.org/home.html
titleCaseStyle:             "AP"
# si true, utilisez /nomfichier.html au lieu de /nomfichier/
uglyURLs:                   false
# verbose output
verbose:                    false
# verbose logging
verboseLog:                 false
# watch filesystem for changes and recreate as needed
watch:                      true
taxonomies:
  - category:               "categories"
  - tag:                    "tags"
---

Configuration TOML

Voici un exemple de fichier de configuration TOML. Les valeurs sous [params] rempliront la variables .Site.Params pour utilisation dans les templates

contentDir = "content"
layoutDir = "layouts"
publishDir = "public"
buildDrafts = false
baseURL = "https://votresite.example.com/"
canonifyURLs = true
title = "Mon Site Hugo"

[taxonomies]
  category = "categories"
  tag = "tags"

[params]
  subtitle = "Hugo est Vraiment Rapide !"
  author = "Jean Valjean"

Toutes les Variables, TOML

Voici la liste complète des variables définies par Hugo dans un exemple de fichier TOML. Les valeurs fournies dans cet exemple représentent les valeurs par défaut utilisées par Hugo.

config.toml
+++
archetypeDir =                "archetypes"
# hostname (and path) to the root, e.g. http://spf13.com/
baseURL =                     ""
# include content marked as draft
buildDrafts =                 false
# include content with publishdate in the future
buildFuture =                 false
# include content already expired
buildExpired =                false
# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
relativeURLs =                false
canonifyURLs =                false
# config file (default is path/config.yaml|json|toml)
config =                     "config.toml"
contentDir =                  "content"
dataDir =                     "data"
defaultExtension =            "html"
defaultLayout =               "post"
# Missing translations will default to this content language
defaultContentLanguage =      "en"
# Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/
defaultContentLanguageInSubdir =  false
disableLiveReload =           false
# Do not build RSS files
disableRSS =                  false
# Do not build Sitemap file
disableSitemap =              false
# Enable GitInfo feature
enableGitInfo =               false
# Build robots.txt file
enableRobotsTXT =             false
# Do not render 404 page
disable404 =                  false
# Do not inject generator meta tag on homepage
disableHugoGeneratorInject =  false
# Allows you to disable all page types and will render nothing related to 'kind';
# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404"
disableKinds = []
# Do not make the url/path to lowercase
disablePathToLower =          false
# Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com
enableEmoji =                 false
# Show a placeholder instead of the default value or an empty string if a translation is missing
enableMissingTranslationPlaceholders = false
footnoteAnchorPrefix =        ""
footnoteReturnLinkContents =  ""
# google analytics tracking id
googleAnalytics =             ""
# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage)
hasCJKLanguage =              false
languageCode =                ""
layoutDir =                   "layouts"
# Enable Logging
log =                         false
# Log File path (if set, logging enabled automatically)
logFile =
# maximum number of items in the RSS feed
rssLimit =                    15
# "toml","yaml", or "json"
metaDataFormat =              "toml"
newContentEditor =            ""
# Don't sync permission mode of files
noChmod =                     false
# Don't sync modification time of files
noTimes =                     false
# Pagination
paginate =                    10
paginatePath =                "page"
# See "content-management/permalinks"
permalinks =
# Pluralize titles in lists using inflect
pluralizeListTitles =         true
# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu")
preserveTaxonomyNames =       false
# filesystem path to write files to
publishDir =                  "public"
# enables syntax guessing for code fences without specified language
pygmentsCodeFencesGuessSyntax = false
# color-codes for highlighting derived from this style
pygmentsStyle =               "monokai"
# true: use pygments-css or false: color-codes directly
pygmentsUseClasses =          false
# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info
SectionPagesMenu =
# default sitemap configuration map
sitemap =
# filesystem path to read files relative from
source =                      ""
staticDir =                   "static"
# display memory and timing of different steps of the program
stepAnalysis =                false
# theme to use (located by default in /themes/THEMENAME/)
themesDir =                   "themes"
theme =                       ""
title =                       ""
# if true, use /filename.html instead of /filename/
uglyURLs =                    false
# verbose output
verbose =                     false
# verbose logging
verboseLog =                  false
# watch filesystem for changes and recreate as needed
watch =                       true
[taxonomies]
  category = "categories"
  tag = "tags"
+++

Variables d’environnement

En plus des 3 options de configuration mentionnées au-dessus, les valeurs-clés de configuration peuvent être définies à travers les variables d’environnement du système d’exploitation.

Par exemple, la commande qui suit réglera le titre d’un site web sur des systèmes de type Unix :

$ env HUGO_TITRE="Un Titre" hugo

Ignorer des Fichiers lors du Rendu

La déclaration qui suit à l’intérieur de ./config.toml amènera Hugo à ignorer les fichiers se terminant par .foo et .boo lors du rendu :

ignoreFiles = [ "\\.foo$", "\\.boo$" ]

Ce qui est au-dessus, c’est une liste d’expressions régulières. Notez que le caractère backslash (\) est échappé, pour faire plaisir à TOML.

Configurer Blackfriday

Blackfriday est le moteur de rendu du Markdown intégré dans Hugo.

Hugo configure généralement Blackfriday avec un ensemble de paramètres plutôt raisonnables. Ces valeurs par défaut devraient correspondre à la plupart des cas d’utilisation.

Cependant, si vous avez des besoins spécifiques concernant Markdown, Hugo enrichit certaines de ses options de comportement Blackfriday afin que vous puissiez les modifier. Le tableau suivant liste ces options Hugo, associées aux marqueurs correspondants du code source de Blackfriday (voir html.go et Markdown.go).

taskLists
default: true
Blackfriday flag:
Purpose: false turns off GitHub-style automatic task/TODO list generation
smartypants
default: true
Blackfriday flag: HTML_USE_SMARTYPANTS
Purpose: false disables smart punctuation substitutions, including smart quotes, smart dashes, smart fractions, etc. If true, it may be fine-tuned with the angledQuotes, fractions, smartDashes, and latexDashes flags (see below).
angledQuotes
default: false
Blackfriday flag: HTML_SMARTYPANTS_ANGLED_QUOTES
Purpose: true enables smart, angled double quotes. Example: “Hugo” renders to renders to «Hugo» instead of “Hugo”.
fractions
default: true
Blackfriday flag: HTML_SMARTYPANTS_FRACTIONS
Purpose: false disables smart fractions.
Example: 5/12 renders to 5⁄12(<sup>5</sup>&frasl;<sub>12</sub>).
Caveat: Even with fractions = false, Blackfriday still converts 1/2, 1/4, and 3/4 respectively to ½ (&frac12;), ¼ (&frac14;) and ¾ (&frac34;), but only these three.
smartDashes
default: true
Blackfriday flag: HTML_SMARTY_DASHES
Purpose: false disables smart dashes; i.e., the conversion of multiple hyphens into an en dash or em dash. If true, its behavior can be modified with the latexDashes flag below.
latexDashes
default: true
Blackfriday flag: HTML_SMARTYPANTS_LATEX_DASHES
Purpose: false disables LaTeX-style smart dashes and selects conventional smart dashes. Assuming smartDashes:
If true, -- is translated into – (&ndash;), whereas --- is translated into — (&mdash;).
However, spaced single hyphen between two words is translated into an en dash— e.g., “12 June - 3 July” becomes 12 June ndash; 3 July upon rendering.
hrefTargetBlank
default: false
Blackfriday flag: HTML_HREF_TARGET_BLANK
Purpose: true opens external links in a new window or tab.
plainIDAnchors
default true
Blackfriday flag: FootnoteAnchorPrefix and HeaderIDSuffix
Purpose: true renders any heading and footnote IDs without the document ID.
Example: renders #my-heading instead of #my-heading:bec3ed8ba720b970
extensions
default: []
Blackfriday flag: EXTENSION_*
Purpose: Enable one or more Blackfriday’s Markdown extensions (if they aren’t Hugo defaults).
Example: Include hardLineBreak in the list to enable Blackfriday’s EXTENSION_HARD_LINK_BREAK
extensionsmask
default: []
Blackfriday flag: EXTENSION_*
Purpose: Enable one or more of Blackfriday’s Markdown extensions (if they aren’t Hugo defaults).
Example: Include autoHeaderIds as false in the list to disable Blackfriday’s EXTENSION_AUTO_HEADER_IDS.
bf-config.toml
[blackfriday]
  angledQuotes = true
  fractions = false
  plainIDAnchors = true
  extensions = ["hardLineBreak"]
bf-config.yml
blackfriday:
  angledQuotes: true
  fractions: false
  plainIDAnchors: true
  extensions:
    - hardLineBreak

Configurer des Formats Output supplémentaires

Hugo v0.20 a introduit la capacité de restituer votre contenu vers plusieurs formats output (par ex., vers JSON, AMP html, ou CSV). Voir Formats Output pour savoir comment ajouter ces valeurs à votre fichier de configuration de projet Hugo.

Specs des Formats de Configuration

La page “Configurer Hugo” a été mise à jour le
Améliorez cette page