Aperçu du style de documentation

• 1: Documentation Style Guide
• 2: Rédiger une nouveau sujet
• 3: Utilisation des modèles de page
• 4: Organisation du contenu
• 5: Hugo Shortcodes personnalisés

1 - Documentation Style Guide

Cette page donne des directives de style d'écriture pour la documentation de Kubernetes. Ce sont des lignes directrices, pas des règles. Faites preuve de discernement et n'hésitez pas à proposer des modifications à ce document dans le cadre d'une pull request.

Pour plus d'informations sur la création de nouveau contenu pour les documents Kubernetes, suivez les instructions surl'utilisation des templates et création d'une pull request de documentation.

Language

La documentation de Kubernetes utilise l'anglais américain comme langue de référence.

Normes de formatage de la documentation

Utilisez le camel case pour les objets d'API

Lorsque vous faites référence à un objet API, utilisez les mêmes lettres majuscules et minuscules que celles utilisées dans le nom d'objet réel. Typiquement, les noms des objets de l'API utilisent le camel case.

Ne divisez pas le nom de l'objet API en mots séparés. Par exemple, utilisez PodTemplateList, et pas Pod Template List.

Référez-vous aux objets de l'API sans dire "objet", à moins que l'omission de "objet" n'entraîne une construction maladroite.

Use angle brackets for placeholders

Use angle brackets for placeholders. Tell the reader what a placeholder represents.

1. Affiche des informations sur un Pod :

   kubectl describe pod <pod-name>
   

   where <pod-name> is the name of one of your Pods.

Use bold for user interface elements

Utiliser l'italique pour définir ou introduire de nouveaux termes.

Utiliser un style de code pour les noms de fichiers, les répertoires et les chemins d'accès

Utiliser la norme internationale pour la ponctuation entre guillemets

Inline code formatting

Use code style for inline code and commands

For inline code in an HTML document, use the <code> tag. In a Markdown document, use the backtick (`).

Utiliser le style de code pour les noms de champs d'objets

Utiliser le style normal pour les chaînes de caractères et les valeurs de champs entiers

Pour les valeurs de champ de type chaîne de caractères ou entier, utilisez un style normal sans guillemets.

Code snippet formatting

Ne pas inclure l'invite de commande

Séparer les commandes de la sortie

Vérifiez que le Pod fonctionne sur le nœud que vous avez choisi :

kubectl get pods --output=wide

La sortie est similaire à celle-ci :

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Versioning Kubernetes examples

Code examples and configuration examples that include version information should be consistent with the accompanying text.

If the information is version specific, the Kubernetes version needs to be defined in the prerequisites section of the Task template or the [Tutorial template] (/docs/contribute/style/page-templates/#tutorial-template). Once the page is saved, the prerequisites section is shown as Before you begin.

Pour spécifier la version de Kubernetes pour une tâche ou une page de tutoriel, incluez min-kubernetes-server-version dans l'entête de la page.

Si l'exemple YAML se trouve dans un fichier autonome, recherchez et passez en revue les sujets qui l'incluent comme référence. Vérifiez que toutes les rubriques utilisant le YAML autonome ont les informations de version appropriées définies. Si un fichier YAML autonome n'est référencé à partir d'aucun sujet, pensez à le supprimer au lieu de le mettre à jour.

Par exemple, si vous écrivez un tutoriel pertinent pour Kubernetes version 1.8, la première partie de votre fichier de démarque doit ressembler à ceci :

---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---

Dans les exemples de code et de configuration, n'incluez pas de commentaires sur les versions alternatives. Veillez à ne pas inclure d'énoncés incorrects dans vos exemples sous forme de commentaires, tels que :

apiVersion: v1 # earlier versions use...
kind: Pod
...

Liste de mots Kubernetes.io

Une liste de termes et de mots spécifiques à Kubernetes à utiliser de manière cohérente sur le site.

Shortcodes

Hugo Shortcodes help create different rhetorical appeal levels. Notre documentation prend en charge trois shortcodes différents dans cette catégorie : Note {{< note >}}, Mise en garde {{< caution >}}, et Avertissement {{< warning >}}.

1. Entourez le texte d'un raccourci d'ouverture et de fermeture.

2. Utilisez la syntaxe suivante pour appliquer un style :

   {{< note >}}
   Il n'est pas nécessaire d'inclure un préfixe ; le shortcode fournit automatiquement (Note:, Caution:, etc.).
   {{< /note >}}
   

La sortie est :

Note

Utilisez {{< note *//>}} pour mettre en surbrillance un conseil ou une information qu'il peut être utile de connaître.

Par exemple :

{{</* note >}}
Vous pouvez _toujours_ utiliser Markdown à l'intérieur de ces légendes.
{{< /note >}}

La sortie est :

Mise en garde

Utilisez {{< caution *//>}} pour attirer l'attention sur une information importante afin d'éviter les pièges.

Par exemple :

{{</* caution >}}
Le style de légende ne s'applique qu'à la ligne directement au-dessus de la balise.
{{< /caution >}}

La sortie est :

Avertissement

Utilisez {{< warning *//>}} pour indiquer un danger ou une information cruciale à suivre.

Par exemple :

{{</* warning >}}
Méfiez-vous.
{{< /warning >}}

La sortie est :

Katacoda Embedded Live Environment

Ce bouton permet aux utilisateurs d'exécuter Minikube dans leur navigateur en utilisant le Katacoda Terminal. Il abaisse le seuil d'entrée en permettant aux utilisateurs d'utiliser Minikube en un seul clic au lieu de passer par l'ensemble du processus d'installation Minikube et Kubectl localement.

The Embedded Live Environment is configured to run minikube start and lets users complete tutorials in the same window as the documentation.

For example:

{{< kat-button >}}

La sortie est :

Common Shortcode Issues

Ordered Lists

Un Shortcode interrompra les listes numérotées à moins que vous ne mettiez une indentation de 4 espaces avant l'avis et l'étiquette.

Par exemple :

1. Préchauffer le four à 350˚F

1. Préparer la pâte et la verser dans un moule à charnière.
   {{< note >}}**Note:** Graisser la casserole pour de meilleurs résultats.{{< /note >}}

1. Cuire au four de 20 à 25 minutes ou jusqu'à ce que ce soit pris.

La sortie est :

1. Préchauffer le four à 350˚F

2. Préparer la pâte et la verser dans un moule à charnière.

   Note: Graisser la casserole pour de meilleurs résultats.

3. Cuire au four de 20 à 25 minutes ou jusqu'à ce que ce soit pris.

Expressions Includes

Les Shortcodes dans les expressions d'include brisera la compilation du site. Vous devez les insérer dans le document parent, avant et après avoir appelé l'include. Par exemple :

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Meilleures pratiques en matière de contenu

Cette section contient des suggestions de pratiques exemplaires pour un contenu clair, concis et cohérent.

Utiliser le présent

Exception : Utilisez le futur ou le passé s'il est nécessaire pour transmettre le sens correct.

Utiliser la voix active

Exception : Utilisez la voix passive si la voix active conduit à une construction maladroite.

Utiliser un langage simple et direct

Utilisez un langage simple et direct. Évitez d'utiliser des expressions inutiles, comme "s'il vous plaît".

S'adresser au lecteur en tant que "vous"

Évitez les phrases latines

Préférez les termes français aux abréviations latines.

Exception : Utilisez "etc." pour et cetera.

Tendances à éviter

Évitez d'utiliser "nous"

L'utilisation du "nous" dans une phrase peut prêter à confusion, car le lecteur pourrait ne pas savoir s'ils font partie du "nous" que vous décrivez.

Évitez le jargon et les expressions idiomatiques

Certains lecteurs parlent le français comme seconde langue. Évitez le jargon et les expressions idiomatiques pour les aider à mieux comprendre.

Évitez les déclarations sur l'avenir

Évitez de faire des promesses ou de donner des conseils sur l'avenir. Si vous avez besoin de parler d'une fonctionnalité alpha, placez le texte sous un titre qui l'identifie comme une fonctionnalité alpha.

Évitez les déclarations qui seront bientôt périmées

Évitez les mots comme "actuellement" et "nouveau". Une caractéristique qui est nouvelle aujourd'hui pourrait ne pas être considérée comme nouvelle dans quelques mois.

A suivre

• En savoir plus sur writing a new topic.
• En savoir plus sur using page templates.
• En savoir plus sur staging your changes
• En savoir plus sur creating a pull request.

2 - Rédiger une nouveau sujet

Cette page montre comment créer un nouveau sujet pour la documentation Kubernetes.

Pré-requis

Créez un fork du dépôt de la documentation de Kubernetes comme décrit dans Commencez à contribuer.

Choisir un type de page

Alors que vous vous préparez à écrire un nouveau sujet, pensez au type de page qui convient le mieux à votre contenu :

Utilisez un modèle pour chaque nouvelle page. Chaque type de page a un template que vous pouvez utiliser lorsque vous écrivez votre sujet. L'utilisation de templates permet d'assurer la cohérence entre les sujets d'un type donné.

Choisir un titre et un nom de fichier

Choisissez un titre qui contient les mots-clés que vous voulez que les moteurs de recherche trouvent. Créez un nom de fichier qui utilise les mots de votre titre séparés par des tirets. Par exemple, le sujet avec titre Using an HTTP Proxy to Access the Kubernetes API has filename http-proxy-access-api.md. Vous n'avez pas besoin de mettre "kubernetes" dans le nom du fichier, car "kubernetes" est déjà dans l'URL du sujet, par exemple :

   /docs/tasks/access-kubernetes-api/http-proxy-access-api/

Ajout du titre du sujet à l'entête

Dans votre sujet, insérez un champ title dans l'entête frontmatter. L'entête est le bloc YAML qui se trouve entre les lignes à trois tirets en haut de la page. En voici un exemple :

---
title: Using an HTTP Proxy to Access the Kubernetes API
---

Choisir un répertoire

En fonction de votre type de page, placez votre nouveau fichier dans un sous-répertoire de l'un d'entre eux :

• /content/en/docs/tasks/
• /content/en/docs/tutorials/
• /content/en/docs/concepts/

Vous pouvez placer votre fichier dans un sous-répertoire existant ou en créer un nouveau.

Placer votre sujet dans la table des matières

La table des matières est construite dynamiquement en utilisant la structure de répertoire de la source de documentation. Les répertoires de niveau supérieur sous /content/fr/docs/ créent une navigation de niveau supérieur, et les sous-répertoires ont chacun des entrées dans la table des matières.

Chaque sous-répertoire possède un fichier _index.md, qui représente la page d'accueil du contenu d'un sous-répertoire donné. Le _index.md n'a pas besoin d'un template. Il peut contenir une vue d'ensemble du contenu des rubriques du sous-répertoire.

Les autres fichiers d'un répertoire sont triés par ordre alphabétique par défaut. Ce n'est presque jamais le meilleur ordre. Pour contrôler le tri relatif des sujets dans un sous-répertoire, définissez la clé weight: front-matter sur un entier. Généralement, nous utilisons des multiples de 10, pour tenir compte de l'ajout de sujets plus tard. Par exemple, un sujet ayant un poids de 10 sera précédé d'un sujet ayant un poids de 20.

Intégrer du code dans votre sujet

Si vous voulez inclure du code dans votre sujet, vous pouvez incorporer le code dans votre fichier directement à l'aide de l'option de syntaxe de bloc de code de markdown. Ceci est recommandé dans les cas suivants (liste non exhaustive) :

• Le code indique la sortie d'une commande telle que kubectl get deploy mydeployment -o json | jq '.status'.
• Le code n'est pas assez générique pour que les utilisateurs puissent l'essayer. Par exemple, vous pouvez intégrer le fichier YAML pour créer un Pod qui dépend d'une implementation Flexvolume spécifique.
• Le code est un exemple incomplet parce qu'il a pour but de mettre en évidence une partie d'un fichier plus volumineux. Par exemple, lorsque vous décrivez des façons de personnaliser l'attribut PodSecurityPolicy pour certaines raisons, vous pouvez fournir un court snippet directement dans le fichier.
• Le code n'est pas destiné à être testé par les utilisateurs pour d'autres raisons. Par exemple, lorsque vous décrivez comment un nouvel attribut doit être ajouté à une ressource à l'aide de la commande kubectl edit, vous pouvez fournir un court exemple qui inclut seulement l'attribut à ajouter.

Inclure le code d'un autre fichier

Une autre façon d'inclure du code dans votre sujet est de créer un nouveau fichier d'exemple complet (ou un groupe de fichiers d'exemple), puis de référencer l'exemple de votre sujet. Utilisez cette méthode pour inclure des exemples de fichiers YAML lorsque l'échantillon est générique et réutilisable, et que vous voulez favoriser leur utilisation.

Lors de l'ajout d'un nouveau fichier d'exemple autonome, tel qu'un fichier YAML, placez le code dans l'un des sous-répertoires <LANG>/examples/ où <LANG> est la langue utilisé dans votre page. Dans votre fichier, utilisez le shortcode codenew :

{{% codenew file="<RELPATH>/my-example-yaml>" %}}

où <RELPATH> est le chemin vers le fichier à inclure, relatif au répertoire examples. Le shortcode Hugo suivant fait référence à un fichier YAML situé sur /content/en/examples/pods/storage/gce-volume.yaml.

{{% codenew file="pods/storage/gce-volume.yaml" %}}

Montrer comment créer un objet API à partir d'un fichier de configuration

Si vous avez besoin de démontrer comment créer un objet API basé sur un fichier de configuration, placez le fichier de configuration dans l'un des sous-répertoires sous <LANG>/examples.

Dans votre sujet, affichez cette commande :

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

Pour un exemple d'un sujet qui utilise cette technique, voir Running a Single-Instance Stateful Application.

Ajouter des images à un sujet

Placez les fichiers images dans le répertoire /images. Le format d'image préféré est SVG.

A suivre

• En savoir plus sur l'utilisation des templates de pages.
• En savoir plus sur le staging de vos changements.
• En savoir plus sur la création d'une pull request.

3 - Utilisation des modèles de page

Lorsque vous ajoutez de nouveaux sujets, appliquez-leur l'un des templates suivants. Ceci standardise l'expérience utilisateur d'une page donnée.

Les templates de page sont dans le répertoire layouts/partials/templates du dépôt kubernetes/website.

Concept template

Une page de concept explique certains aspects de Kubernetes. Par exemple, une page conceptuelle peut décrire l'objet Kubernetes Deployment et expliquer le rôle qu'il joue en tant qu'application une fois qu'il est déployé, dimensionné et mis à jour. Généralement, les pages conceptuelles n'incluent pas de séquences d'étapes, mais fournissent plutôt des liens vers des tâches ou des tutoriels.

Pour écrire une nouvelle page concept, créez un fichier Markdown dans un sous-répertoire du répertoire /content/fr/docs/concepts, avec les caractéristiques suivantes :

• Dans l'entête YAML de la page, définissez content_type: concept.

• Dans le corps de la page, définissez les variables capture requises et les variables optionnelles que vous voulez inclure :

  Variable	Required?
  overview	yes
  body	yes
  whatsnext	no

  Le corps de la page ressemblera à ceci (supprimez toutes les captures optionnelles dont vous n'avez pas besoin) :

  {{% capture overview %}}
  
  {{% /capture %}}
  
  {{% capture body %}}
  
  {{% /capture %}}
  
  {{% capture whatsnext %}}
  
  {{% /capture %}}
  

• Remplissez chaque section de contenu. Suivez ces lignes directrices :

  • Organiser le contenu avec les rubriques H2 et H3.
  • Pour overview, définir le contexte du sujet à l'aide d'un seul paragraphe.
  • Pour body, expliquer le concept.
  • Pour whatsnext, fournir une liste à puces de sujets (5 au maximum) pour en apprendre davantage sur le concept.

Annotations est un exemple publié du template de concept. Cette page utilise également le modèle de concept.

Template de tâche

Une page de tâches montre comment faire une seule chose, généralement en donnant une courte séquence d'étapes. Les pages de tâches ont une explication minimale, mais fournissent souvent des liens vers des sujets conceptuels qui fournissent un contexte et des connaissances connexes.

Pour écrire une nouvelle page de tâches, créez un fichier Markdown dans un sous-répertoire du répertoire /content/fr/docs/tasks, avec les caractéristiques suivantes :

• Dans l'entête YAML de la page, définissez content_type: task.

• Dans le corps de la page, définissez les variables capture requises et les variables optionnelles que vous voulez inclure :

  Variable	Required?
  overview	yes
  prerequisites	yes
  steps	no
  discussion	no
  whatsnext	no

  Le corps de la page ressemblera à ceci (supprimez toutes les captures optionnelles dont vous n'avez pas besoin) :

  {{% capture overview %}}
  
  {{% /capture %}}
  
  {{% capture prerequisites %}}
  
  {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
  
  {{% /capture %}}
  
  {{% capture steps %}}
  
  {{% /capture %}}
  
  {{% capture discussion %}}
  
  {{% /capture %}}
  
  {{% capture whatsnext %}}
  
  {{% /capture %}}
  

• Dans chaque section, écrivez votre contenu. Suivez les directives suivantes :

  • Utilisez un minimum d'en-têtes H2 (avec deux caractères # en tête de liste). Les sections elles-mêmes sont intitulées automatiquement par le modèle.
  • Pour overview, utilisez un paragraphe pour définir le contexte de l'ensemble du sujet.
  • Pour prerequisites, utiliser des listes à puces dans la mesure du possible. Commencez à ajouter des prérequis supplémentaires sous la balise include. Les conditions préalables par défaut incluent un cluster Kubernetes en cours d'exécution.
  • Pour steps, utiliser des listes numérotées.
  • Pour la discussion, utilisez le contenu normal pour développer l'information couverte dans la section steps.
  • Pour whatsnext, donnez une liste de 5 sujets au maximum qui peuvent être intéressant à lire ensuite.

Voici un exemple de sujet publié qui utilise le template de tasks Using an HTTP proxy to access the Kubernetes API.

Tutorial template

Une page de tutoriel montre comment atteindre un objectif qui est plus grand qu'une seule tâche. Typiquement, une page de tutoriel comporte plusieurs sections, chacune d'entre elles ayant une séquence d'étapes. Par exemple, un tutoriel pourrait fournir un aperçu d'un exemple de code qui illustre une certaine caractéristique de Kubernetes. Les didacticiels peuvent inclure des explications au niveau de la surface, mais devraient être reliés à des sujets connexes sur les concepts pour des explications approfondies.

Pour écrire une nouvelle page de tutoriel, créez un fichier Markdown dans un sous-répertoire du répertoire /content/fr/docs/tutorials, avec les caractéristiques suivantes :

• Dans l'entête YAML de la page, définissez content_type: tutorial.

• Dans le corps de la page, définissez les variables capture requises et les variables optionnelles que vous voulez inclure :

  Variable	Required?
  overview	yes
  prerequisites	yes
  objectives	yes
  lessoncontent	yes
  cleanup	no
  whatsnext	no

  Le corps de la page ressemblera à ceci (supprimez toutes les captures optionnelles dont vous n'avez pas besoin) :

  {{% capture overview %}}
  
  {{% /capture %}}
  
  {{% capture prerequisites %}}
  
  {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
  
  {{% /capture %}}
  
  {{% capture objectives %}}
  
  {{% /capture %}}
  
  {{% capture lessoncontent %}}
  
  {{% /capture %}}
  
  {{% capture cleanup %}}
  
  {{% /capture %}}
  
  {{% capture whatsnext %}}
  
  {{% /capture %}}
  

• Dans chaque section, écrivez votre contenu. Suivez les directives suivantes :

  • Utilisez un minimum d'en-têtes H2 (avec deux caractères # en tête de liste). Les sections elles-mêmes sont intitulées automatiquement par le template.
  • Pour overview, utiliser un paragraphe pour définir le contexte de l'ensemble du sujet.
  • Pour prerequisites, utiliser des listes à puces dans la mesure du possible. Ajoutez des prérequis supplémentaires en dessous de ceux inclus par défaut.
  • Pour objectives, utiliser des listes à puces.
  • Pour lessoncontent, utiliser un mélange de listes numérotées et de contenu narratif, le cas échéant.
  • Pour cleanup, utiliser des listes numérotées pour décrire les étapes de nettoyage de l'état du cluster une fois la tâche terminée.
  • Pour whatsnext, Donnez une liste de 5 sujets au maximum qu'il serait intéressant à lire ensuite.

Voici un exemple de sujet publié qui utilise le modèle de tutoriel Running a Stateless Application Using a Deployment.

A suivre

• En savoir plus sur le style guide
• En savoir plus sur l'organisation des contenus

4 - Organisation du contenu

Ce site utilise Hugo. Dans Hugo, l'organisation du contenu est un concept de base.

Listes de pages

Ordre des pages

Le menu latéral de la documentation, le navigateur de la page de documentation, etc. sont listés selon l'ordre de tri par défaut de Hugo, qui trie par poids (à partir de 1), par date (la plus récente en premier), et enfin par titre du lien.

Si vous voulez déplacer une page ou une section vers le haut, placez un poids dans l'entête de la page :

title: My Page
weight: 10

Menu principal de la documentation

Le menu principal Documentation est construit à partir des sections ci-dessous docs/ avec le drapeau main_menu placé dans l'entête du fichier de contenu de la section `_index.md' :

main_menu: true

Notez que le titre du lien est récupéré à partir du linkTitle de la page, donc si vous voulez qu'il soit différent du titre, changez-le dans le fichier du contenu cible :

main_menu: true
title: Page Title
linkTitle: Title used in links

Menu latéral de documentation

Le menu latéral de la barre de documentation est construit à partir de l'arborescence de la section courante commençant sous docs/.

Il affichera toutes les sections et leurs pages.

Si vous ne voulez pas lister une section ou une page, mettez l'option toc_hide à true dans l'entête :

toc_hide: true

Lorsque vous naviguez vers une section contenant du contenu, la section ou la page spécifique (par exemple _index.md) est affichée. Sinon, la première page à l'intérieur de cette section est affichée.

Navigateur de documentation

Le navigateur de page sur la page d'accueil de la documentation est construit en utilisant toutes les sections et pages qui sont directement sous la section docs.

Si vous ne voulez pas lister une section ou une page, mettez l'option toc_hide à true dans la partie avant :

toc_hide: true

Menu principal

Les liens du site dans le menu en haut à droite -- et aussi dans le pied de page -- sont construits par des recherches de pages. C'est pour s'assurer que la page existe réellement. Ainsi, si la section case-studies n'existe pas dans un site (langue), le lien n'apparaitra pas.

Paquets de pages

In addition to standalone content pages (Markdown files), Hugo supports Page Bundles.

One example is Custom Hugo Shortcodes. On considère qu'il s'agit d'un "paquet de feuilles". Tout ce qui se trouve sous le répertoire, y compris le fichier `index.md', fera partie du paquet. Cela inclut également les liens relatifs aux pages, les images qui peuvent être traitées, etc :

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

Un autre exemple largement utilisé est celui du paquet includes. Il définit headless : true dans l'entête, ce qui signifie qu'il n'obtient pas son propre URL. Il n'est utilisé que dans d'autres pages.

en/includes
├── default-storage-class-prereqs.md
├── federated-task-tutorial-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

Quelques notes importantes sur les fichiers dans les paquets :

• Pour les paquets traduits, tous les fichiers non contenus manquants seront hérités des fichiers de langue anglaise. Cela permet d'éviter les doublons.
• Tous les fichiers d'un bundle sont ce que Hugo appelle Resources et vous pouvez fournir des métadonnées par langue, comme les paramètres et le titre, même s'il ne prend pas en charge les entêtes (fichiers YAML etc.). Voir Page Resources Metadata.
• La valeur que vous obtenez de .RelPermalink d'un Resource est relative à la page. Voir Permalinks.

Styles

La source SASS des feuilles de style pour ce site est stockée sous src/sass et peut être construite avec make sass (notez que Hugo aura bientôt le support SASS, voir https://github.com/gohugoio/hugo/issues/4243.

A suivre

• Hugo shortcodes personnalisés
• Style guide

5 - Hugo Shortcodes personnalisés

Cette page explique les shortcodes Hugo personnalisés pouvant être utilisés dans la documentation de Kubernetes Markdown.

En savoir plus sur shortcodes dans la documentation Hugo.

Etat de la fonctionnalité

Dans une page de Markdown (fichier .md) de ce site, vous pouvez ajouter un code court pour afficher la version et l'état de la fonction documentée.

Feature state demo

Ci-dessous se trouve une démo de l'extrait d'état de la fonctionnalité, qui affiche la fonctionnalité comme stable dans Kubernetes version 1.10.

{{< feature-state for_k8s_version="v1.10" state="stable" >}}

Rend à :

Les valeurs valides pour state sont :

• alpha
• beta
• deprecated
• stable

Feature state code

La version de Kubernetes affichée par défaut est celle de la page ou du site. Ceci peut être modifié en passant le paramètre for_k8s_version shortcode.

{{< feature-state for_k8s_version="v1.10" state="stable" >}}

Rend à :

Alpha feature

{{< feature-state feature-state state="alpha" >}}

Rend à :

Beta feature

{{< feature-state feature-state state="beta" >}}

Rend à :

Stable feature

{{< feature-state feature-state state="stable" >}}

Rend à :

Deprecated feature

{{< feature-state feature-state state="deprecated" >}}

Rend à :

Glossaire

Vous pouvez faire référence à des termes du glossaire avec une inclusion qui met à jour et remplace automatiquement le contenu avec les liens pertinents de notre glossaire. When the term is moused-over by someone using the online documentation, the glossary entry displays a tooltip.

The raw data for glossary terms is stored at https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary, with a content file for each glossary term.

Démonstration du glossaire

Par exemple, le snippet suivant est rendu à cluster avec une infobulle :

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

Tabs

Dans une page de démarque (fichier .md) de ce site, vous pouvez ajouter un jeu d'onglets pour afficher plusieurs saveurs d'une solution donnée.

The tabs shortcode takes these parameters:

• name: Le nom tel qu'il apparaît sur l'onglet.
• codelang: Si vous fournissez un contenu interne au shortcode tab, vous pouvez indiquer à Hugo quel langage de code utiliser pour activer la coloration syntaxique.
• include: Le fichier à inclure dans l'onglet. Si l'onglet vit dans un Hugo leaf bundle, le fichier -- qui peut être n'importe quel type MIME supporté par Hugo -- est recherché dans le bundle lui-même. Si ce n'est pas le cas, la page de contenu qui doit être incluse est recherchée par rapport à la page en cours. Notez qu'avec le include, vous n'avez pas de contenu interne de shortcode et devez utiliser la syntaxe de fermeture automatique. Par exemple, {{< tab name="Content File #1" include="example1" />}}. La langue doit être spécifiée sous codelang ou la langue est prise en compte en fonction du nom du fichier. Les fichiers non contenus sont mis en surbrillance par défaut.
• Si votre contenu interne est Markdown, vous devez utiliser le délimiteur % pour entourer l'onglet. Par exemple, {{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}
• Vous pouvez combiner les variations mentionnées ci-dessus dans un ensemble d'onglets.

Ci-dessous se trouve une démo du raccourci des onglets.

Tabs demo: Code highlighting

{{< tabs name="tab_with_code" >}}
{{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}}
{{< /tabs >}}

Rend à:

• Tab 1
• Tab 2

echo "This is tab 1."

println "This is tab 2."

Tabs demo: Inline Markdown and HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}
It can even contain shortcodes.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>Plain HTML</h3>
	<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}

Rend à:

• Markdown
• HTML

Tabs demo: File include

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

Rend à:

• Content File #1
• Content File #2
• JSON File

{
  "apiVersion": "v1",
  "kind": "PodTemplate",
  "metadata": {
    "name": "nginx"
  },
  "template": {
    "metadata": {
      "labels": {
        "name": "nginx"
      },
      "generateName": "nginx-"
    },
    "spec": {
        "containers": [{
          "name": "nginx",
          "image": "dockerfile/nginx",
          "ports": [{"containerPort": 80}]
        }]
    }
  }
}

A suivre

• En savoir plus sur Hugo.
• En savoir plus sur écrire un nouveau sujet.
• En savoir plus sur l'utilisation des page templates.
• En savoir plus sur staging your changes
• En savoir plus sur créer une pull request.