Contribuer à la Documentation Hugo
Créez votre Fork
Il est préférable d’apporter des modifications aux documents Hugo sur votre machine locale pour vérifier la cohérence du style visuel. Assurez-vous d’avoir créé un fork d’hugoDocs sur GitHub et cloné le dépôt localement sur votre machine. Pour plus d’informations, vous pouvez regarder la documentation de GitHub sur “forking” ou suivre le guide de contribution au développement de Hugo.
Vous pouvez ensuite créer une branche distincte pour vos ajouts. Assurez-vous de choisir un nom de branche descriptif qui correspond le mieux au type de contenu. Voici un exemple de nom de branche que vous pourriez utiliser pour ajouter un nouveau site Web à la vitrine :
git checkout -b jean-dupont-ajout-galerie-sites-hugo
Ajouter du Nouveau Contenu
La documentation Hugo fait un usage intense de la fonctionnalité archétypes d’Hugo. Toutes les sections de contenu de la documentation de Hugo ont un archétype attribué.
L’ajout de nouveaux contenus aux documents Hugo suit le même modèle, quelle que soit la section de contenu :
hugo new <DOCS-SECTION>/<nouveau-contenu-basdecasse>.md
Ajouter une Nouvelle Fonction
Une fois que vous avez cloné le dépôt Hugo, vous pouvez créer une nouvelle fonction via la commande suivante. Gardez le nom du fichier en minuscule.
hugo new functions/nouvellefonction.md
L’archétype pour functions selon le thème Hugo est comme suit :
---
linktitle: ""
description: ""
godocref: ""
publishdate: ""
lastmod: ""
categories: [functions]
tags: []
ns: ""
signature: []
workson: []
hugoversion: ""
aliases: []
relatedfuncs: []
toc: false
deprecated: false
---
Nouveaux Champs Obligatoires de Fonction
Voici une analyse des champs de front matter générés automatiquement pour vous en utilisant hugo new functions/* :
title- ceci sera pré-rempli en bas de casse quand vous utilisez le générateur
hugo new. linktitle- la casse réelle de la fonction (par exemple,
replaceREplutôt quereplacere). description- Une brève description utilisée pour remplir la Référence rapide des fonctions.
categories- actuellement auto-remplie avec
functionspour des raisons d’avenir et de portabilité seulement ; ignorez ce champ. tags- seulement si vous pensez que cela aidera les utilisateurs finaux à trouver d’autres fonctions connexes
signature- ceci est une définition de signature/syntaxe pour l’appel de fonction (par ex.,
apply SEQUENCE FUNCTION [PARAM...]). workson- les valeurs acceptables sont composées de
listes,taxonomies,termes,groupes, etfichiers. hugoversion- la version d’Hugo qui sera livré avec cette nouvelle fonction.
relatedfuncs- autres fonctions de modélisation que vous pressentez en rapport avec vos nouvelles fonctions pour aider les utilisateurs collègues Hugo.
{{.Content}}- une description augmentée de la nouvelle fonction ; les exemples ne sont pas seulement bienvenus mais vivement encouragés.
Dans le corps de votre fonction, développez la courte description utilisée dans le front matter. Incluez le plus grand nombre d’exemples possibles et tirez parti de Hugo docs code shortcode. Si vous ne parvenez pas à ajouter des exemples, mais souhaitez solliciter l’aide de la communauté Hugo, ajoutez needsexample: true à votre front matter.
Ajouter un Nouveau Tutoriel
Une fois que vous avez cloné le dépôt Hugo, vous pouvez créer un nouveau tutoriel via la commande suivante. Nommez le fichier de réduction en conséquence :
hugo new tutorials/mon-nouveau-tutoriel.md
L’archetype pour le type de contenu tutorials est comme suit :
---
linktitle: ""
description: ""
godocref: ""
publishdate: ""
lastmod: ""
categories: [tutorials]
tags: []
author: ""
authorurl: ""
originalurl: ""
draft: false
aliases: []
notesforauthors: "Go to gohugo.io/contribute/documentation for more info."
---
Ajouter des Blocs de Code
Les blocs de code sont essentiels pour fournir des exemples de nouvelles fonctionnalités de Hugo aux utilisateurs finaux de la documentation Hugo. Dans la mesure du possible, créez des exemples que vous pensez que les utilisateurs Hugo pourront mettre en œuvre dans leurs propres projets.
Syntaxe Standard
Dans toutes les pages des docs Hugo, on utilise la syntaxe typique markdown du “triple-back-tick”. Si vous ne souhaitez pas prendre plus de temps pour implémenter les codes courts du code suivant, utilisez le markdown standard enrichi par GitHub. Les Hugo docs utilisent une version de highlight.js avec un ensemble spécifique de langages.
Vos options pour les langages sont xml/html, go/golang, md/markdown/mkd, handlebars, apache, toml, yaml, json, css, asciidoc, ruby, powershell/ps, scss, sh/zsh/bash/git, http/https, et javascript/js.
```html
<h1>Salut le monde !</h1>
```
Shortcode de Bloc de Code
La documentation Hugo contient un shortcode très robuste pour l’ajout de blocs de code interactifs.
code
code est le shortcode de la documentation Hugo que vous utiliserez le plus souvent. code ne requiert qu’un paramètre nommé : file. Voici le modèle :
{{% code file="smart/file/name/with/path.html" download="download.html" copy="true" %}}
```langage
Un bon paquet de code peut aller ici !
```
{{% /code %}}
Ce qui suit sont les arguments passés à l’intérieur de code:
file- Le seul argument * requis *. Le
fileest nécessaire pour le style, mais joue également un rôle important pour aider les utilisateurs à créer un modèle mental autour de la structure de répertoire de Hugo. Visuellement, cela sera affiché en tant que texte en haut à gauche du bloc de code. download- if omitted, this will have no effect on the rendered shortcode. When a value is added to
download, it’s used as the filename for a downloadable version of the code block. copy- Un bouton de copie est ajouté automatiquement à tous les shortcodes
code. Si vous souhaitez conserver le nom de fichier et le style decode, mais ne souhaitez pas encourager les lecteurs à copier le code (par exemple, un extrait “Ne faites pas” dans un didacticiel), utilisezcopy="false".
Exemple Input code
Cet exemple de bloc de code HTML indique aux utilisateurs de Hugo ce qui suit :
- Ce fichier pourrait vivre dans
layouts/_default, comme démontré parlayouts/_default/single.htmlen tant que valeur pourfile. - Cet extrait est suffisamment complet pour être téléchargé et mis en œuvre dans un projet Hugo, comme démontré par
download="single.html".
{{% code file="layouts/_default/single.html" download="single.html" %}}
```html
{{ define "main" }}
<main>
<article>
<header>
<h1>{{.Title}}</h1>
{{with .Params.subtitle}}
<span>{{.}}</span>
</header>
<div>
{{.Content}}
</div>
<aside>
{{.TableOfContents}}
</aside>
</article>
</main>
{{ end }}
```
{{% /code %}}
Exemple Affichage ‘code’
L’output de cet exemple sera rendu dans la doc Hugo comme suit :
{{ define "main" }}
<main>
<article>
<header>
<h1>{{.Title}}</h1>
{{with .Params.subtitle}}
<span>{{.}}</span>
</header>
<div>
{{.Content}}
</div>
<aside>
{{.TableOfContents}}
</aside>
</article>
</main>
{{ end }}
Citations
Les blocs de citation peuvent être ajoutés à la documentation de Hugo en utilisant la syntaxe typique de blockquote de Markdown :
> Without the threat of punishment, there is no joy in flight.
La citation précédente sera rendue comme suit dans la documentation Hugo :
Without the threat of punishment, there is no joy in flight.
Cependant, vous pouvez ajouter un élément «` simple et rapide (ajouté sur le client via JavaScript) en séparant votre citation principale et la citation avec un trait d’union avec un seul espace de chaque côté :
> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)
Ce qui sortira comme suit dans la doc Hugo :
Without the threat of punishment, there is no joy in flight. - Kobo Abe
Admonitions
Admonitions are common in technical documentation. The most popular is that seen in reStructuredText Directives. From the SourceForge documentation:
Admonitions are specially marked “topics” that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. - SourceForge
La documentation Hugo contient trois admonitions : note, tip, et warning.
note Admonition
Utilisez le shortcode note quand vous voulez attirer l’attention subtilement vers l’information. note est conçu pour être moins une interruption dans le contenu que ne l’est le warning.
Exemple Input note
{{% note %}}
Voici un élément d'information sur lequel je souhaiterais attirer votre **attention**.
{{% /note %}}
Exemple note Output
<aside class="admonition note">
<div class="note-icon">
</div>
<div class="admonition-content"><p>Here is a piece of information I would like to draw your <strong>attention</strong> to.</p>
</div>
</aside>
Exemple note Display
tip Admonition
Use the tip shortcode when you want to give the reader advice. tip, like note, is intended to be less of an interruption in content than is warning.
Exemple tip Input
{{% tip %}}
Here's a bit of advice to improve your productivity with Hugo.
{{% /tip %}}
Exemple tip Output
<aside class="admonition tip">
<div class="tip-icon">
</div>
<div class="admonition-content"><p>Here’s a bit of advice to improve your productivity with Hugo.</p>
</div>
</aside>
Exemple tip Display
warning Admonition
Use the warning shortcode when you want to draw the user’s attention to something important. A good usage example is for articulating breaking changes in Hugo versions, known bugs, or templating “gotchas.”
Exemple warning Input
{{% warning %}}
This is a warning, which should be reserved for *important* information like breaking changes.
{{% /warning %}}
Exemple Output warning
<aside class="admonition warning">
<div class="admonition-icon">
</div>
<div class="admonition-content"><p>This is a warning, which should be reserved for <em>important</em> information like breaking changes.</p>
</div>
</aside>