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 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.
Learning about tutorials
To interactively learn about the features described on this page, launch the tutorial on writing tutorials using the button below.
Writing a tutorial
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 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 custom element format:
<walkthrough-directive-name param="optional parameter"> </walkthrough-directive-name>
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 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.
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 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>
The list of possible spotlight targets is as follows:
|Cloud Console Spotlight Targets||Description|
||Button to open Cloud Shell, near top right.|
||Opens Orion editor, on Cloud Shell's top bar.|
||Opens a web preview window for Cloud Shell.|
To spotlight a Cloud Shell Editor element instead, follow this format:
<walkthrough-editor-spotlight spotlightId="target" text="label text"> </walkthrough-editor-spotlight>
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 spotlightId="navigator" filePath="hello.md" text="My file"> </walkthrough-editor-spotlight>
Other supported editor spotlight targets:
|Editor Spotlight Targets||Description|
||Highlights the file menu button.|
||Highlights the edit menu button.|
||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:
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 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.
Launching tutorials in Cloud Shell
There are three ways to kickstart a Walkthrough in Cloud Shell:
Run the following command in your Cloud Shell session to launch a tutorial from an existing file,
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](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)
Run the following
cloudshellcommand in your Cloud Shell session to launch a tutorial from an existing Markdown file,
cloudshell launch-tutorial tutorial.md