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>
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:
Use the
cloudshell launch-tutorial
commandRun 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
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:[](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.