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 :

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, replaceRE plutôt quereplacere).

description

Une brève description utilisée pour remplir la Référence rapide des fonctions.

categories

actuellement auto-remplie avec functions pour 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, et fichiers.

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 file est 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 de code, mais ne souhaitez pas encourager les lecteurs à copier le code (par exemple, un extrait “Ne faites pas” dans un didacticiel), utilisez copy="false".

Exemple Input code

Cet exemple de bloc de code HTML indique aux utilisateurs de Hugo ce qui suit :

1. Ce fichier pourrait vivre dans layouts/_default, comme démontré par layouts/_default/single.html en tant que valeur pour file.
2. 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&rsquo;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>

Exemple d’Affichage warning