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 étape par étape au format Markdown. Cloud Shell crée des tutoriels en contexte à partir de ces fichiers Markdown en analysant le texte en étapes et sous-étapes qui sont ensuite affichées dans le panneau de droite de Google Cloud Console.

Tutoriel ouvert

Découvrir les tutoriels (avec un tutoriel !)

Pour en savoir plus sur les tutoriels interactifs en suivant un tutoriel existant, lancez le tutoriel d'écriture de tutoriels à l'aide du bouton ci-dessous :

Ouvrir dans Cloud Shell

Écrire un tutoriel

Les tutoriels sont écrits au format Markdown (plus précisément au format CommonMark, sans HTML) et peuvent être développés à l'aide de n'importe quel éditeur de texte. Vous pouvez également ajouter des directives à tutoriel, qui incluent des fonctionnalités avancées, telles que la mise en évidence et l'ajout d'icônes en ligne, avec un Markdown spécifique au tutoriel pour le rendre plus facile à suivre.

Créer des étapes

Lors de la création d'un tutoriel, les en-têtes sont importants pour déterminer sa structure. Pour définir les bons titres et en-têtes d'étapes, et les instructions sous-jacentes, suivez la hiérarchie ci-dessous :

  • Balises H1 (#) pour le titre du tutoriel. Il ne doit y avoir qu'une seule balise H1 dans le 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 Walkthrough

## First step

Hello World

### Part 1

Part One Instructions.

### Part 2

Part Two Instructions.

## Conclusion

Done!

Ajouter un bloc de code

Pour faire apparaître un extrait de code, encadrez-le d'accents graves, comme suit :

```
print("hello world")
```

L'extrait de code obtenu est accompagné d'un bouton "Copier dans le presse-papiers" situé dans l'angle droit.

Ajouter des directives

Pour ajouter une directive (fonctionnalité avancée, comme mettre en évidence un élément d'interface utilisateur, afficher une icône en ligne et déclencher des actions de fichier), utilisez le format d'élément personnalisé suivant :

<walkthrough-directive-name param="optional parameter">
</walkthrough-directive-name>

Dans ce format, 'directive-name' et 'param' sont des espaces réservés. Par exemple, si vous souhaitez utiliser la directive editor-open-file et le paramètre filePath, utilisez ce format :

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

Créer un effet de surbrillance

Un effet de surbrillance est un focus visuel qui aide les utilisateurs à trouver un élément d'interface utilisateur spécifique dans la console.

Pour mettre en surbrillance un élément de la console, utilisez ce format :

<walkthrough-spotlight-pointer spotlightId="target" text="label text">
</walkthrough-spotlight-pointer>

Ainsi, si vous souhaitez mettre en surbrillance le bouton permettant d’ouvrir la fenêtre d’aperçu sur le Web de Cloud Shell, utilisez :

<walkthrough-spotlight-pointer spotlightId="devshell-web-preview-button"
                               text="Open Cloud Shell">
</walkthrough-spotlight-pointer>

Pour les éléments de l'éditeur, choisissez la directive editor-spotlight. Pour mettre en surbrillance un fichier hello.md existant lorsqu'un utilisateur clique sur "Mon fichier", utilisez :

<walkthrough-editor-spotlight spotlightId="navigator" filePath="hello.md"
                              text="My file">
</walkthrough-editor-spotlight>

Astuce : Pour les éléments d'interface utilisateur qui n'ont pas d'ID Spotlight, vous pouvez utiliser un sélecteur CSS.

Insérer une icône dans un texte

Pour appeler efficacement l'utilisation d'un bouton de console, utilisez une icône en ligne.

Par exemple, <walkthrough-cloud-shell-editor-icon></walkthrough-cloud-shell-editor-icon> produit une icône en ligne de l'icône de l'éditeur Cloud Shell Icône Cloud Shell.

Déclencher des actions de fichier

De plus, vous pouvez ajouter des liens dans votre tutoriel qui ouvrent des fichiers utiles pour les utilisateurs. Pour ouvrir un fichier dans Cloud Editor lorsque votre utilisateur parcourt votre tutoriel et clique sur le texte "Ouvrir un exemple de fichier" affiché, utilisez la directive suivante :

<walkthrough-editor-open-file filePath="path/to/test.md"
                              text="Open sample file">
</walkthrough-editor-open-file>

Remarque : Le fichier doit exister sur l'instance Cloud Shell des utilisateurs, et le chemin de fichier fourni doit lui être associé. Le fichier doit, en outre, être situé dans le répertoire d’accueil ou dans l'un de ses sous-répertoires.

Trouver les bonnes directives

Consultez la documentation de référence sur Markdown pour les tutoriels pour obtenir une liste complète de toutes les mises en surbrillance possibles (et de leurs paramètres) à votre disposition.

Lancement de 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 à partir d'un site Web, d'un blog ou d'un projet open source vers votre tutoriel hébergé dans un dépôt git. La fonctionnalité "Ouvrir dans Cloud Shell" permet d'ajouter un paramètre "cloudshell_tutorial" et peut être ajoutée à la fin de l'URL en tant que tel &cloudshell_tutorial=path/to/file.md pour spécifier l'emplacement du fichier Markdown source dans le dépôt. Cela signifie que le Markdown pour un bouton lié à votre tutoriel ressemblerait à :

    [![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.png)](https://ssh.cloud.google.com/cloudshell/open?cloudshell_git_repo=https://github.com/testuser/myproject&cloudshell_tutorial=resources/hello.md)
    

Étapes suivantes