Cloud Shell supports building and launching tutorials to help users familiarize themselves with your project quickly and effectively.
A 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 a panel in Google Cloud console.
Write tutorials
Tutorials are written in CommonMark Markdown. Additional Markdown extensions are supported, as are directives, which include advanced functionality like spotlighting features and adding inline icons.
Steps
When creating a tutorial, headings are important in determining its structure. To set the correct title, step headings, and underlying instructions, use the following hierarchy:
- H1 (#) tags for the tutorial title. There should only be one H1 tag in a 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!
Directives
Directives enable advanced functionality like spotlighting features and adding inline icons.
To add a directive, use the following format:
<walkthrough-DIRECTIVE_NAME PARAMETER="PARAMETER_VALUE">
</walkthrough-DIRECTIVE_NAME>
For example, if you'd like to use the directive editor-open-file
and the
parameter filePath
, it would be written as follows:
<walkthrough-editor-open-file filePath="test/hello.md">
</walkthrough-editor-open-file>
For the available directives, refer to the directives reference.
Launch tutorials in Cloud Shell
There are two ways to kickstart a tutorial in Cloud Shell:
Use the
cloudshell launch-tutorial
commandRun 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
Alternatively, you can use the
teachme
alias by running the following command in your Cloud Shell session to launch a tutorial 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 tutorial hosted in a Git repository. The Open in Cloud Shell feature allows for a
cloudshell_tutorial
parameter, which can be added to the end of the URL to specify the location of the source Markdown file in the repository. 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://ssh.cloud.google.com/cloudshell/open?cloudshell_git_repo=GIT_REPO_URL&cloudshell_tutorial=PATH_TO_MD_FILE)
Next steps
- For a comprehensive list of tutorial-specific Markdown expressions, see the Tutorial Markdown reference.
- For guidelines on how to write effective tutorials, see the Tutorial style guide.