Tutorials in Cloud Shell

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

A Cloud Shell 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 the right hand panel on the Google Cloud Console.

Cloud Shell Tutorial in Action

Writing a tutorial

Tutorials are written in Markdown - specifically, in CommonMark format, and without HTML - and can be developed using any text editor. You can also add directives which include advanced functionality, like spotlighting and adding inline icons, with tutorial specific Markdown in your tutorial and make it easier to follow. To add a directive, use the following format:

`walkthrough <directive-name> [optional parameters]`

Create Steps

When creating a tutorial, headings are important in determining its structure. To set the right title, step headings, and underlying instructions, follow the hierarchy below:

  • H1 (#) tags for the tutorial title. There should only be a single H1 tag in the 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


Add a Code Block

To callout a code snippet, use backticks as follows:

```<code snippet>```

The resulting code snippet comes with a copy-to-clipboard button in the right-hand corner.

Create a spotlight

A spotlight is a visual focus to help users find a specific UI element of the Cloud Console.

To spotlight a Cloud Console element, use this format:

`walkthrough spotlight-pointer <spotlight-id> "<label text>"`

Putting it into practice, if you'd like to spotlight the button to open the web preview window for Cloud Shell, use:

`walkthrough spotlight-pointer devshell-web-preview-button "Open Cloud Shell"`

The list of possible spotlight targets is as follows:

Cloud Console Spotlight Targets Description
devshell-activate-button Button to open Cloud Shell, near top right.
devshell-web-editor-button Opens Orion editor, on Cloud Shell's top bar.
devshell-web-preview-button Opens a web preview window for Cloud Shell.

To spotlight a Cloud Shell Editor element instead, follow this format:

`walkthrough editor-spotlight <spotlight-id> "<label text>"`

Using the above format, you can spotlight an existing hello.md file with the editor-spotlight when a user clicks 'My file', by running:

`walkthrough editor-spotlight navigator hello.md "My file"`

Other supported editor spotlight targets:

Editor Spotlight Targets Description
fileMenu Highlights the file menu button.
editMenu Highlights the edit menu button.
navigator Highlight a file specified in the item field.

Use an inline icon

To effectively call out the use of a Cloud Console button, use an inline icon.

The following are icons available for use:

Directive Description
`walkthrough cloud-shell-icon` Cloud Shell Icon
`walkthrough web-preview-icon` Web Preview Icon
`walkthrough orion-editor-icon` Orion Editor Icon

Trigger file actions

Additionally, you can have links in your tutorial that open useful files for users. To open a file in Cloud Editor as your user walks through your tutorial and clicks on the display text, 'Open sample file', use the following directive:

`walkthrough editor-open-file path/to/test.md "Open sample file"`

Note, the file must exist on the users' Cloud Shell instance and the provided path must be its relative file path. The file must be located in the Home directory or in any of the Home directory's subdirectories.

Launching tutorials in Cloud Shell

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

  1. Use the teachme command

    Run 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. The 'Open in Cloud Shell' feature allows for a 'tutorial' parameter, and can be added to the end of the URL as such &tutorial=path/to/file.md. This means that the Markdown for a button linked to your tutorial would look like:

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

  3. 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

Send feedback about...

Cloud Shell