Scrivere tutorial in Cloud Shell

Cloud Shell supporta la creazione e l'avvio di tutorial per aiutare gli utenti a familiarizzare con il tuo progetto in modo rapido ed efficace.

Un tutorial è un insieme di istruzioni scritte in Markdown. Cloud Shell crea tutorial in-context da questi file Markdown analizzando il testo in passaggi e sottopassaggi che vengono poi visualizzati in un riquadro nella console Google Cloud.

Un tutorial in esecuzione in Cloud Shell

Scrivere tutorial

I tutorial sono scritti in CommonMark Markdown. Sono supportate altre estensioni Markdown, così come le directive, che includono funzionalità avanzate come funzionalità di messa in evidenza e l'aggiunta di icone in linea.

Passaggi

Quando crei un tutorial, le intestazioni sono importanti per determinare la sua struttura. Per impostare il titolo, le intestazioni dei passaggi e le istruzioni sottostanti corretti, utilizza la seguente gerarchia:

  • Tag H1 (#) per il titolo del tutorial. In un tutorial deve essere presente un solo tag H1.
  • Tag H2 (##) per il titolo di un passaggio.
  • Tag H3 (###) per il titolo di un passaggio secondario.

Ecco un file Markdown di esempio che puoi utilizzare per creare un tutorial:

# First tutorial

## First step

Hello world

### Part 1

Part one instructions.

### Part 2

Part two instructions.

## Conclusion

Done!

Direttive

Le direttive consentono funzionalità avanzate come mettere in evidenza le funzionalità e aggiungere icone in linea.

Per aggiungere una direttiva, utilizza il seguente formato:

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

Ad esempio, se vuoi utilizzare l'istruzione editor-open-file e il parametro filePath, la scrittura sarà la seguente:

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

Per le direttive disponibili, consulta il riferimento alle direttive.

Avviare i tutorial in Cloud Shell

Esistono due modi per avviare un tutorial in Cloud Shell:

  1. Utilizzare il comando cloudshell launch-tutorial

    Esegui il seguente comando cloudshell nella sessione Cloud Shell per avviare un tutorial da un file Markdown esistente, tutorial.md:

    cloudshell launch-tutorial tutorial.md

    In alternativa, puoi utilizzare l'alias teachme eseguendo il seguente comando nella sessione Cloud Shell per avviare un tutorial da un file esistente, hello.md:

    teachme hello.md

  2. Utilizzare Apri in Cloud Shell

    In alternativa, puoi utilizzare la funzionalità Apri in Cloud Shell per indirizzare gli utenti da un sito web, un blog o un progetto open source al tuo tutorial ospitato in un repository Git. La funzionalità Apri in Cloud Shell consente di utilizzare un parametro cloudshell_tutorial, che può essere aggiunto alla fine dell'URL per specificare la posizione del file Markdown di origine nel repository. Ciò significa che il Markdown per un pulsante collegato al tuo tutorial sarà simile al seguente:

    [![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)

Passaggi successivi