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.
Learn about tutorials (using a tutorial!)
To learn about interactive tutorials by working through an actual interactive tutorial, launch the tutorial on writing tutorials with the following button:
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.