Referência do Markdown para tutoriais

Os tutoriais do Cloud Shell, conhecidos como instruções, ajudam os usuários a se familiarizar com seu projeto de maneira rápida e eficaz, além de serem fáceis de configurar e iniciar. Um tutorial do Cloud Shell é um conjunto de instruções escritas em CommonMark Markdown. Ele também pode incluir diretivas, que são expressões de Markdown específicas do tutorial, para adicionar funcionalidades avançadas, como destaque e seleção de projetos.

Consulte o guia Como escrever tutoriais para saber como configurar, compor e iniciar um tutorial no Cloud Shell.

Formato da diretiva

Para adicionar uma diretiva, use o seguinte formato:

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

Nesse formato, "directive-name" e "param" são marcadores. Por exemplo, se você quiser usar a diretiva editor-open-file e o parâmetro filePath, use este formato:

<walkthrough-editor-open-file filePath="test/hello.md">
</walkthrough-editor-open-file>

Diretivas do Cloud Shell

As tabelas abaixo listam as diretivas e seus respectivos parâmetros, disponíveis para usar na criação de um tutorial do Cloud Shell.

Tutorial sobre metadados e layout

Diretiva: autor

<walkthrough-author></walkthrough-author>

A tag de autor define os metadados sobre o autor. Todos os parâmetros são opcionais.

Parâmetros Descrição
name Nome do autor
repositoryUrl Link para o repositório que é usado para feedback
tutorialName ID do tutorial

Diretiva: duração do tutorial

<walkthrough-tutorial-duration></walkthrough-tutorial-duration>

A tag de duração do tutorial exibe um ícone de relógio e uma mensagem estimando quanto tempo ele levará.

Parâmetros Descrição
duration Duração estimada do tutorial em minutos.

Diretiva: cartão de tutorial sugerido

<walkthrough-tutorial-card></walkthrough-tutorial-card>

Uma tag de cartão do tutorial é vinculada a um tutorial sugerido.

Parâmetros Descrição
url URL para o tutorial.
icon Nome do ícone
label Rótulo para análise de eventos de clique

Diretiva: nota de rodapé

<walkthrough-footnote>Footnote text here</walkthrough-footnote>

Uma diretiva de nota de rodapé define o texto como uma nota de rodapé na parte inferior da etapa. O texto da nota de rodapé é escrito como o texto interno.

Seleção de projeto

Diretiva: configuração do projeto

<walkthrough-project-setup></walkthrough-project-setup>

O componente de configuração do projeto ajuda o usuário a criar ou selecionar um projeto para usar. Essa etapa impedirá que o usuário continue até que um projeto válido seja selecionado.

A tag de permissões do projeto define as permissões de projeto necessárias para o tutorial. Se o usuário não tiver as permissões no projeto selecionado, a configuração dele não o considerará válido.

Consulte a documentação para ver uma descrição de como as permissões do projeto funcionam.

Parâmetros Descrição
permissions (Opcional) Lista separada por vírgulas das permissões necessárias

Diretiva: configuração do projeto e cobrança

<walkthrough-project-billing-setup></walkthrough-project-billing-setup>

O componente de configuração do projeto e do faturamento ajuda o usuário a criar ou selecionar um projeto a ser usado. Essa etapa impedirá que o usuário continue até que um projeto válido com faturamento ativado seja selecionado.

Parâmetros Descrição
permissions (Opcional) Lista separada por vírgulas das permissões necessárias

Destaques e botões

Diretiva: indicador de destaques

<walkthrough-spotlight-pointer>Label text here</walkthrough-spotlight-pointer>

A diretiva de indicador de destaques cria um rótulo clicável que destacará o elemento de interface do usuário especificado na tela. Apenas um dos parâmetros é necessário. Se ambos forem fornecidos, o spotlightId será usado.

O indicador pode selecionar um elemento por código de instrumentação, que é uma propriedade no elemento DOM, ou usando um seletor de CSS. Os dois tipos de seletores permitem que os seletores separados por vírgulas correspondam aos elementos. Todos os elementos que corresponderem ao seletor serão destacados.

O texto do rótulo é escrito como o texto interno.

Parâmetros Descrição
spotlightId Código de instrumentação, pode-se usar vírgulas para separar vários códigos
cssSelector Um seletor de CSS
Destinos de destaque/IDs de instrumentação Descrição
console-nav-menu Menu de navegação do console, três traços no canto superior esquerdo
devshell-activate-button Botão para abrir o Cloud Shell, perto do canto superior direito
devshell-web-editor-button Abre o editor Orion, na barra superior do Cloud Shell.
devshell-web-preview-button Abre uma janela de visualização da Web para o Cloud Shell

Para destaques no frame do editor, consulte a seção Diretivas do editor.

Diretiva: ativar APIs

<walkthrough-enable-apis></walkthrough-enable-apis>

O componente de ativação de APIs cria um botão que ativa as APIs quando clicado. Isso permitirá que seu projeto acesse as APIs do GCP.

Consulte a documentação para saber quais APIs você pode ativar.

Parâmetros Descrição
apis Lista separada por vírgulas de APIs a serem ativadas

Diretiva: abrir o Cloud Shell

<walkthrough-open-cloud-shell-button></walkthrough-open-cloud-shell-button>

O componente para abrir o Cloud Shell cria um botão que abre o Cloud Shell quando clicado (com o projeto atual selecionado).

Parâmetros Descrição
open-cloud-shell Abre o Cloud Shell quando a etapa principal é mostrada

Diretiva: abrir o Cloud Shell em segundo plano

<walkthrough-devshell-precreate></walkthrough-devshell-precreate>

A diretiva devshell-precreate provisiona uma instância do Cloud Shell em segundo plano para que o carregamento seja mais rápido. e é executado quando a etapa é mostrada

Variáveis dinâmicas

Diretiva: vinculação de dados

<walkthrough-watcher-constant></walkthrough-watcher-constant>

Tutoriais permitem ativar a vinculação de dados em pares de chave-valor. Os valores são definidos por diretivas ou pela estrutura do tutorial. Eles podem ser definidos na sessão do tutorial usando a diretiva watcher-constant.

Depois, o valor da string pode ser referenciado com:

{{<key>}}

Exemplo de uso em Markdown:

# My Walkthrough

## Step 1

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

My message: {{my-key}}

Existem chaves integradas disponíveis:

Key Descrição do valor
project-id O código do projeto atual do usuário
project-name O nome do projeto do usuário

Diretiva: observador constante

<walkthrough-watcher-constant></walkthrough-watcher-constant>

Um observador é uma string dinâmica que pode ser definida para um tutorial. Uma constante do observador define o valor no início do tutorial. Consulte a seção de vinculação de dados para mais informações.

Parâmetros Descrição
key Chave para o inspetor
value Valor do inspetor

Diretiva: ícones inline

<walkthrough-inline-icon-name></walkthrough-inline-icon-name>

"inline-icon-name" é um marcador para o ícone que você quer especificar (como nav-menu-icon e conclusion-trophy).

Os ícones a seguir são estilizados como ícones inline.

Nome do ícone inline Icon
cloud-shell-icon Ícone do Cloud Shell
web-preview-icon Ícone de visualização da Web
cloud-shell-editor-icon Ícone do editor do Cloud Shell
nav-menu-icon Ícone do menu de navegação
notification-menu-icon Ícone do menu de notificação
pin-section-icon Ícone para fixar a seção do menu

Os seguintes ícones são estilizados como imagens.

Nome do ícone inline Icon
conclusion-trophy Troféu de conclusão

Diretivas do editor do Cloud Shell

As diretivas do editor são aceitas na página editor do Cloud Shell.

Diretiva: abrir arquivo

<walkthrough-editor-open-file></walkthrough-editor-open-file>

A diretiva de abrir arquivo cria um rótulo clicável para abrir um arquivo do disco do Cloud Shell no editor.

O texto do rótulo é escrito como o texto interno.

Parâmetros Descrição
filePath Caminho de arquivo relativo

Diretiva: abrir texto selecionado no editor

<walkthrough-editor-select-line></walkthrough-editor-select-line>

A diretiva editor-select-line cria um rótulo clicável para abrir um arquivo no editor e selecionar uma linha de texto dentro dele.

Parâmetros Descrição
filePath Caminho de arquivo relativo
startLine Linha inicial
startCharacterOffset Índice inicial
endLine Linha final
endCharacterOffset Índice final

Diretiva: abrir texto regex especificado no editor

<walkthrough-editor-select-regex>Label text here</walkthrough-editor-select-regex>

A diretiva editor-select-regex cria um rótulo clicável para abrir um arquivo no editor e seleciona texto nele, com base no regex fornecido.

Parâmetros Descrição
filePath Caminho de arquivo relativo
regex Regex para correspondência

O texto do rótulo é escrito como o texto interno.

Diretiva: indicador de destaques

<walkthrough-editor-spotlight>Label text here</walkthrough-editor-spotlight>

A diretiva de indicador de destaque cria um rótulo clicável que destaca o elemento da IU especificado dentro do editor na tela.

O indicador só pode selecionar alvos predefinidos.

Parâmetros Descrição
spotlightId Código do editor

O texto do rótulo é escrito como o texto interno.

Alvos de destaques do editor Descrição
fileMenu Destaca o botão do menu "Arquivo".
editMenu Destaca o botão do menu "Editar".
navigator Destaca um arquivo especificado no campo do item.