Tutorial Markdown Reference

Cloud Shell tutorials, also known as Walkthroughs, help users familiarize themselves with your project quickly and effectively, while being easy to setup and launch. A Cloud Shell tutorial is a set of instructions written in CommonMark Markdown. It can also include directives which are tutorial specific Markdown expressions to add advanced functionality like spotlighting and project selection.

Refer to the Writing tutorials guide for how to set up, compose, and launch a tutorial in Cloud Shell.

Directive format

To add a directive, use the following format:

<walkthrough-directive-name param-name="param-value">
</walkthrough-directive-name>

Cloud Shell directives

The tables below list the directives, and their respective parameters, available for use when authoring a Cloud Shell tutorial.

Tutorial Metadata and Layout

Author

The author tag defines metadata about the author. All parameters are optional.

author Creates metadata for the tutorial author.
name Author's name.
repositoryUrl Link to the repository which is used for feedback.
tutorialName Tutorial id

Tutorial Duration

The tutorial duration tag renders a clock icon and message estimating how long the tutorial will take.

tutorial-duration Displays a tutorial duration.
duration Estimated tutorial duration in minutes.

Tutorial Card

A tutorial card tag links to a suggested tutorial.

tutorial-card Display a suggested tutorial.
url URL to the tutorial.
icon Icon name.
label Label for analytics for click events.

Footnote

A footnote directive styles the text as a footnote at the bottom of the step.

Footnote text is written as the inner text.

footnote Displays text as a footnote.

Project Selection

Project Setup

The project setup component helps the user create or select a project to use. This step will block the user from continuing until a valid project has been selected.

The project permissions tag sets required project permissions for the tutorial. If the user lacks the permissions on the selected project, the project setup will not consider it a valid project.

See the documentation for a description of how project permissions work.

project-setup Substitutes the project setup step.
permissions (Optional) Comma separated list of required permissions.

Project and Billing Setup

The project and billing setup component helps the user create or select a project to use. This step will block the user from continuing until a valid project with billing enabled has been selected.

project-billing-setup Substitutes the project setup step with billing required.
permissions (Optional) Comma separated list of required permissions.

Spotlights and buttons

Spotlight pointer

The spotlight pointer directive creates a clickable label that will spotlight the specified UI element on the screen. Only one of the parameters is needed. If both are provided, the spotlightId will be used.

The pointer can select an element by instrumentation id, which is a property on the DOM element, or by using a CSS selector. Both types of selectors allow comma separated selectors to match elements. All elements matching the selector will be highlighted.

Label text is written as the inner text.

spotlight-pointer Substitutes a spotlight pointer.
spotlightId Instrumentation id, can use commas to separate multiple ids.
cssSelector A CSS selector
Cloud Console Spotlight Targets Description
console-nav-menu Console navigation menu, hamburger in top left.
devshell-activate-button Button to open Cloud Shell, near top right.
devshell-web-editor-button Opens Orion editor, on Cloud Shell's top bar.
devshell-web-preview-button Opens a web preview window for Cloud Shell.

Enable APIs

The enable APIs component creates a button that enables APIs when clicked. This will allow your project to access the GCP APIs.

See the documentation for which APIs you can enable.

enable-apis Diplays a component to enable APIs.
apis Comma separated list of APIs to enable.

Open Cloud Shell

The open Cloud Shell component creates a button that opens Cloud Shell when clicked.

open-cloud-shell-button Diplays a component to open Cloud Shell with the current project selected.
open-cloud-shell Opens Cloud Shell when the parent step is viewed.
devshell-precreate Provisions a Cloud Shell instance in background so the load is faster. Runs when the step is shown.

Dynamic Variables

Data Binding

Walkthroughs allow data binding for key value pairs. The values are set by directives or by the tutorial framework. They can be defined within the tutorial session using the directive watcher-constant.

Afterwards, the string value can be referenced with:

{{<key>}}

Example usage in Markdown:

# My Tutorial

## Step 1

<walkthrough-watcher-constant key="my-key" value="Hello Google">
</walkthrough-watcher-constant>

My message: {{my-key}}

There are built-in keys available:

Data Name Value Description
project-id The user's current project id.
project-name The user's project name.

Watcher Constant

A Watcher is a dynamic string that can be set for a tutorial. A watcher constant defines the value at the beginning of the tutorial. See the data binding section for more information.

watcher-constant Defines a string value at render time.
key Key to the watcher.
value Value of the watcher.

Icon Directives

The following icons are styled as inline icons.

Directive Icon
cloud-shell-icon Cloud Shell Icon
web-preview-icon Web Preview Icon
cloud-shell-editor-icon Cloud Shell Editor Icon
nav-menu-icon Nav Menu Icon
notification-menu-icon Notification Menu Icon
pin-section-icon Pin Menu Section Icon

The following icons are styled as images.

Directive Icon
conclusion-trophy Conclusion Trophy

Cloud Shell Editor Directives

Editor directives are supported by the Cloud Shell Editor page.

Open file

The open file directive creates a clickable label to open a file from the Cloud Shell disk.

Label text is written as the inner text.

editor-open-file Opens a file from Cloud Shell in the Editor.
filePath Relative file path

Select text

The select text directive creates a clickable label to open an file and select text within it.

editor-select-line Selects specified text in the editor.
filePath Relative file path
startLine Start line
startCharacterOffset Start index
endLine End line
endCharacterOffset End index
editor-select-regex Selects specified text in the editor.
filePath Relative file path
regex Regex to match

Label text is written as the inner text.

Spotlight pointer

The spotlight pointer directive creates a clickable label that will spotlight the specified UI element on the screen.

The pointer can only select predefined targets.

editor-spotlight Spotlights a predefined target.
spotlightId Editor id

Label text is written as the inner text.

Editor Spotlight Targets Description
fileMenu Highlights the file menu button.
editMenu Highlights the edit menu button.
navigator Highlight a file specified in the item field.
Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Shell