Writing Walkthroughs in Cloud Shell

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

A Walkthrough is a set of instructions written in Markdown. Cloud Shell creates in-context Walkthroughs 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.

Learning about Walkthroughs (using a Walkthrough!)

To learn about interactive Walkthroughs by working through an actual interactive Walkthrough, launch the Walkthrough on writing Walkthroughs using the button below:

Writing a Walkthrough

Walkthroughs are written in Markdown - specifically, in CommonMark format, and without HTML - and can be developed using any text editor. You can also add directives to your Walkthrough which include advanced functionality, like spotlighting and adding inline icons, with Walkthrough-specific Markdown to make it easier to follow.

Create Steps

When creating a Walkthrough, 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 Walkthrough title. There should only be a single H1 tag in the Walkthrough.
• 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 Walkthrough:

# First Walkthrough

## First step

Hello World

### Part 1

Part One Instructions.

### Part 2

Part Two Instructions.

## Conclusion

Done!

Add a Code Block

To callout a code snippet, use backticks as follows:

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

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

Add directives

To add a directive (advanced walkthrough functionality like spotlighting a UI element, displaying an inline icon, and triggering file actions), use the following custom element format:

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

In this format, 'directive-name' and 'param' are placeholders. For example, if you'd like to use the directive, editor-open-file, and the parameter, filePath, use this format:

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

Note: Parameters are strings separated by whitespace. Quotes around the parameters are optional. If the parameter does contain whitespace, such as the label text for a spotlight pointer, quotes are required.

Create a spotlight

A spotlight is a visual focus to help users find a specific UI element within Console.

To spotlight a Console element, use this format:

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

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 spotlightId="devshell-web-preview-button"
                               text="Open Cloud Shell">
</walkthrough-spotlight-pointer>

For elements within the editor, choose to use the editor-spotlight directive. To spotlight an existing hello.md file when a user clicks 'My file', use:

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

Tip: For UI elements that don't have spotlight IDs, you can use a CSS selector.

Use an inline icon

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

For example, <walkthrough-cloud-shell-editor-icon></walkthrough-cloud-shell-editor-icon> produces an inline icon of the Cloud Shell editor icon .

Trigger file actions

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

<walkthrough-editor-open-file filePath="path/to/test.md"
                              text="Open sample file">
</walkthrough-editor-open-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.

Find the right directives

Look up the Walkthrough Markdown Reference for an extensive list of all possible spotlights (and their parameters) available to you.

Launching Walkthroughs in Cloud Shell

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

Note: To launch a Walkthrough in developer mode, use `cloudshell launch-tutorial -d tutorial-name.md`.

1. Use the cloudshell launch-tutorial command

   Run the following cloudshell command in your Cloud Shell session to launch a Walkthrough 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 Walkthrough 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 Walkthrough hosted in a git repository. 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 to specify the location of the source Markdown file in the repository. This means that the Markdown for a button linked to your Walkthrough would look like:

   [![Open in Cloud Shell](https://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)
   

Next Steps

• For a comprehensive list of Walkthrough-specific Markdown expressions, see the Walkthrough Markdown Reference.
• For guidelines on how to write effective Walkthroughs, see the Walkthrough Writing Guide.