Criar tutoriais no Cloud Shell

O Cloud Shell oferece suporte à criação e ao lançamento de tutoriais para ajudar os usuários a se familiarizarem com seu projeto de maneira rápida e eficaz.

Um tutorial é um conjunto de instruções escritas no Markdown. O Cloud Shell cria tutoriais em contexto com base nesses arquivos Markdown analisando o texto em etapas e subetapas que são exibidas em um painel no console do Google Cloud.

Um tutorial em execução no Cloud Shell

Saber mais sobre tutoriais (usando um tutorial)

Para saber mais sobre os tutoriais interativos, siga as etapas de um tutorial interativo real. Inicie o tutorial sobre como escrever tutoriais com o seguinte botão:

Abrir no Cloud Shell

Criar tutoriais

Os tutoriais são escritos em CommonMark Markdown. As extensões de marcação adicionais são compatíveis, assim como as diretivas, que incluem funcionalidades avançadas, como recursos de destaque e ícones inline adicionais.

Etapas

Ao criar um tutorial, os títulos são importantes para determinar a estrutura. Para definir o título correto, os cabeçalhos das etapas e as instruções subjacentes, use a seguinte hierarquia:

  • Tags H1 (#) para o título do tutorial. Deve haver apenas uma tag H1 em um tutorial.
  • Tags H2 (##) para o título de uma etapa.
  • Tags H3 (###) para o título de uma subetapa.

Veja um exemplo de arquivo do Markdown que você pode usar para criar um tutorial:

# First tutorial

## First step

Hello world

### Part 1

Part one instructions.

### Part 2

Part two instructions.

## Conclusion

Done!

Diretivas

As diretivas permitem funcionalidades avançadas, como destacar recursos e adicionar ícones in-line.

Para adicionar uma diretiva, use o seguinte formato:

<walkthrough-DIRECTIVE_NAME PARAMETER="PARAMETER_VALUE">
</walkthrough-DIRECTIVE_NAME>

Por exemplo, se você quiser usar a diretiva editor-open-file e o parâmetro filePath, ela será escrita da seguinte maneira:

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

Para ver as diretivas disponíveis, consulte a referência das diretivas.

Iniciar tutoriais no Cloud Shell

Há duas maneiras de iniciar um tutorial no Cloud Shell:

  1. Usar o comando cloudshell launch-tutorial

    Execute o seguinte comando cloudshell na sua sessão do Cloud Shell para iniciar um tutorial por meio de um arquivo Markdown atual, tutorial.md:

    cloudshell launch-tutorial tutorial.md

    Como alternativa, use o alias teachme executando o seguinte comando na sessão do Cloud Shell para iniciar um tutorial por meio de um arquivo atual, hello.md:

    teachme hello.md

  2. Use Open in Cloud Shell

    Como alternativa, você pode usar o recurso Abrir no Cloud Shell para orientar seus usuários a partir de um site, blog ou projeto de código aberto para seu tutorial hospedado em um repositório do Git. O recurso Abrir no Cloud Shell permite que um parâmetro cloudshell_tutorial seja adicionado ao final do URL para especificar o local do arquivo Markdown de origem no repositório. Isso significa que o Markdown para um botão vinculado ao seu tutorial seria o seguinte:

    [![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)

Próximas etapas