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.
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]`
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:
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|
||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 <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|
||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 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:
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](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)
Run the following
cloudshellcommand in your Cloud Shell session to launch a tutorial from an existing Markdown file,
cloudshell launch-tutorial tutorial.md