Como 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 passo a passo é um conjunto de instruções escritas no Markdown. O Cloud Shell cria tutoriais em contexto desses arquivos Markdown, analisando o texto em etapas e subetapas que são exibidas no painel à direita do Console do Google Cloud.

Instruções em ação

Aprendendo sobre tutoriais (usando um tutorial!)

Para aprender sobre tutoriais interativos, trabalhando com um tutorial interativo real, inicie a seção sobre como escrever tutoriais usando o botão abaixo:

Abrir no Cloud Shell

Como escrever um tutorial

As instruções são escritas no Markdown, especificamente no formato CommonMark e sem HTML, e podem ser desenvolvidas com qualquer editor de texto. Você também pode adicionar diretivas ao seu tutorial, que incluem funcionalidades avançadas, como destaque e adição de ícones inline, com o Markdown específico das instruções para facilitar o acompanhamento.

Criar etapas

Ao criar um tutorial, os títulos são importantes para determinar a estrutura. Para definir o título, os cabeçalhos e as instruções certas, siga a hierarquia abaixo:

  • Tags H1 (#) para o título do tutorial. Só deve haver uma tag H1 no tutorial.
  • Tags H2 (##) para o título de uma etapa.
  • Tags H3 (###) para o título de uma subetapa.

Aqui está um exemplo de arquivo Markdown que você pode usar para criar um tutorial:

# First Walkthrough

## First step

Hello World

### Part 1

Part One Instructions.

### Part 2

Part Two Instructions.

## Conclusion

Done!

Adicionar um bloco de código

Para chamar um snippet de código, use acentos graves da seguinte maneira:

```
print("hello world")
```

O snippet de código resultante vem com um botão de cópia para a área de transferência no canto direito.

Adicionar diretivas

Para adicionar uma diretiva (funcionalidade avançada do tutorial, como destacar um elemento da IU, exibir um ícone inline e acionar ações de arquivo), use o seguinte formato de elemento personalizado:

<walkthrough-directive-name param="optional parameter">
</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>

Criar um destaque

Um destaque é um foco visual para ajudar os usuários a encontrar um elemento específico da IU no Console.

Para destacar um elemento do console, use este formato:

<walkthrough-spotlight-pointer spotlightId="target" text="label text">
</walkthrough-spotlight-pointer>

Em outras palavras, se você quiser destacar o botão para abrir a janela de visualização da Web para o Cloud Shell, faça o seguinte:

<walkthrough-spotlight-pointer spotlightId="devshell-web-preview-button"
                               text="Open Cloud Shell">
</walkthrough-spotlight-pointer>

Para elementos dentro do editor, escolha usar a diretiva editor-spotlight. Para destacar um arquivo hello.md existente quando um usuário clicar em "Meu arquivo", use:

<walkthrough-editor-spotlight spotlightId="navigator" filePath="hello.md"
                              text="My file">
</walkthrough-editor-spotlight>

Dica: para elementos da interface do usuário que não possuem IDs de destaque, use um seletor de CSS.

Usar um ícone in-line

Para chamar a atenção sobre o uso de um botão do Console, use um ícone inline.

Por exemplo, <walkthrough-cloud-shell-editor-icon></walkthrough-cloud-shell-editor-icon> produz um ícone inline do ícone do editor do Cloud Shell Ícone do Cloud Shell.

Acionar ações do arquivo

Além disso, seu tutorial pode ter links que abrem arquivos úteis para os usuários. Para abrir um arquivo no Cloud Editor à medida que o usuário avança no tutorial e clica no texto de exibição "Abrir arquivo de amostra", use a seguinte diretiva:

<walkthrough-editor-open-file filePath="path/to/test.md"
                              text="Open sample file">
</walkthrough-editor-open-file>

Observe que o arquivo precisa existir na instância do Cloud Shell dos usuários e o caminho fornecido precisa ser o caminho de arquivo relativo. O arquivo precisa estar localizado no diretório inicial ou em qualquer subdiretório dele.

Encontrar as diretivas certas

Consulte a Referência de Markdown de tutoriais para acessar uma lista extensa de todos os destaques possíveis (e seus parâmetros) disponíveis para você.

Como 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 a partir de um arquivo Markdown existente, 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 a partir de um arquivo existente, hello.md:

    teachme hello.md
    
  2. Use "Open in Cloud Shell"

    Outra opção é usar o recurso "Abrir no Cloud Shell" para guiar seus usuários de um site, blog ou projeto de código aberto para o tutorial hospedado em um repositório Git. O recurso '"brir no Cloud Shell" permite um parâmetro "cloudshell_tutorial" e pode ser adicionado ao final do URL como &cloudshell_tutorial=path/to/file.md para especificar o local do arquivo Markdown de origem no repositório. Isso significa que o Markdown de um botão vinculado ao seu tutorial seria semelhante a:

    [![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.png)](https://ssh.cloud.google.com/cloudshell/open?cloudshell_git_repo=https://github.com/testuser/myproject&cloudshell_tutorial=resources/hello.md)
    

A seguir