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.

A tutorial running in Cloud Shell

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