Write tutorials in Cloud Shell

Cloud Shell supports building and launching tutorials to help users familiarize themselves with your project quickly and effectively.

A tutorial is a set of instructions written in Markdown. Cloud Shell creates in-context tutorials from these Markdown files by parsing the text into steps and substeps that are then displayed in a panel in Google Cloud console.

Write tutorials

Tutorials are written in CommonMark Markdown . Additional Markdown extensions are supported, as are directives , which include advanced functionality like spotlighting features and adding inline icons .

Steps

When creating a tutorial, headings are important in determining its structure. To set the correct title, step headings, and underlying instructions, use the following hierarchy:

• H1 (#) tags for the tutorial title. There should only be one H1 tag in a tutorial.
• H2 (##) tags for a step title.
• H3 (###) tags for a sub-step title.

Here is a sample Markdown file you can use to create a tutorial:

 # First tutorial

## First step

Hello world

### Part 1

Part one instructions.

### Part 2

Part two instructions.

## Conclusion

Done! 

Directives

Directives enable advanced functionality like spotlighting features and adding inline icons.

To add a directive, use the following format:

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

For example, if you'd like to use the directive editor-open-file and the parameter filePath , it would be written as follows:

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

For the available directives, refer to the directives reference .

Launch tutorials in Cloud Shell

There are two ways to kickstart a tutorial in Cloud Shell:

1. Use the cloudshell launch-tutorial command

   Run the following cloudshell command in your Cloud Shell session to launch a tutorial from an existing Markdown file, tutorial.md :

    cloudshell launch-tutorial tutorial.md 
   

   Alternatively, you can use the teachme alias by running the following command in your Cloud Shell session to launch a tutorial from an existing file, hello.md :

    teachme hello.md 
   

2. Use Open in Cloud Shell

   Alternatively, you can use the Open in Cloud Shell feature to guide your users from a website, blog, or open source project to your tutorial hosted in a Git repository. The Open in Cloud Shell feature allows for a cloudshell_tutorial parameter, which can be added to the end of the URL to specify the location of the source Markdown file in the repository. This means that the Markdown for a button linked to your tutorial would look like:

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

Next steps

• For a comprehensive list of tutorial-specific Markdown expressions, see the Tutorial Markdown reference .
• For guidelines on how to write effective tutorials, see the Tutorial style guide .