Rédiger des tutoriels dans Cloud Shell

Cloud Shell prend en charge la création et le lancement de tutoriels pour aider les utilisateurs à se familiariser rapidement et efficacement avec votre projet.

Un tutoriel est un ensemble d'instructions rédigées au format Markdown. Cloud Shell crée des tutoriels contextualisés à partir de ces fichiers Markdown en décomposant leur contenu en étapes et sous-étapes, et en affichant celles-ci dans un panneau de la console Google Cloud.

Tutoriel s'exécutant dans Cloud Shell

Rédiger des tutoriels

Les tutoriels sont rédigés au format CommonMark Markdown. D'autres extensions Markdown sont acceptées (de même que les directives) et incluent des fonctionnalités avancées telles que les fonctionnalités de mise en avant et ajouter des icônes intégrées.

Étapes

Lors de la création d'un tutoriel, les titres sont particulièrement importants afin de déterminer sa structure. Pour définir les bons titres et en-têtes d'étapes, ainsi que les instructions sous-jacentes, utilisez la hiérarchie suivante:

  • Balises H1 (#) pour le titre du tutoriel Il ne devrait y avoir qu'une seule balise H1 dans un tutoriel.
  • Balises H2 (##) pour un titre d'étape
  • Balises H3 (##) pour un titre de sous-étape

Voici un exemple de fichier Markdown que vous pouvez utiliser pour créer un tutoriel :

# First tutorial

## First step

Hello world

### Part 1

Part one instructions.

### Part 2

Part two instructions.

## Conclusion

Done!

Directives

Les directives permettent d'activer des fonctionnalités avancées, telles que la mise en surbrillance des fonctionnalités et l'ajout d'icônes intégrées.

Pour ajouter une instruction, utilisez le format suivant :

<walkthrough-DIRECTIVE_NAME PARAMETER="PARAMETER_VALUE">
</walkthrough-DIRECTIVE_NAME>

Par exemple, si vous souhaitez utiliser la directive editor-open-file et le paramètre filePath, l'instruction s'écrirait comme suit:

<walkthrough-editor-open-file filePath="test/hello.md">
</walkthrough-editor-open-file>

Pour obtenir des instructions disponibles, reportez-vous à la documentation de référence des directives.

Lancer des tutoriels dans Cloud Shell

Il existe deux façons de démarrer un tutoriel dans Cloud Shell :

  1. Apprenez à utiliser la commande cloudshell launch-tutorial.

    Exécutez la commande cloudshell suivante dans votre session Cloud Shell pour lancer un tutoriel à partir d'un fichier Markdown existant, tutorial.md :

    cloudshell launch-tutorial tutorial.md

    Vous pouvez également utiliser l'alias teachme en exécutant la commande suivante dans votre session Cloud Shell pour lancer un tutoriel à partir d'un fichier existant, hello.md :

    teachme hello.md

  2. Utilisez Ouvrir dans Cloud Shell

    Vous pouvez également utiliser la fonctionnalité Ouvrir dans Cloud Shell pour guider vos utilisateurs depuis un site Web, un blog ou un projet Open Source vers votre tutoriel hébergé dans un dépôt Git. La fonctionnalité Ouvrir dans Cloud Shell autorise un paramètre cloudshell_tutorial, qui peut être ajouté à la fin de l'URL pour spécifier l'emplacement du fichier Markdown source dans le dépôt. Ainsi, l'expression Markdown pour un bouton associé à votre tutoriel ressemblerait à ceci :

    [![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.png)](https://ssh.cloud.google.com/cloudshell/open?cloudshell_git_repo=GIT_REPO_URL&cloudshell_tutorial=PATH_TO_MD_FILE)

Étapes suivantes