Criando um tutorial no formato de Codelabs
Tags: codelabs, tutorial, programming
Published: 2022-03-14 03:44:53

## Início
### Problema Inicial
Quem nunca se deparou com dezenas de páginas de documentação e se perdeu no momento de tentar aprender algo novo?
Não importa o quão profundo, especial ou acertivo o seu guia é, **o usuário irá perder o interesse na sua documentação ou guia depois de 30 segundos tentando se encontrar no meio de tantas páginas.**
Portanto, diversas "Bigtechs" criaram sites e ferramentas para guiar o usuário e facilitar o aprendizado de determinada linguagem e ferramenta.
<br />

### Objetivo
[Google Developers Codelabs](https://codelabs.developers.google.com/) é um site que provê tutoriais guiados e intuítivos para auxiliar no aprendizado de desenvolvedores, e este guia tem como objetivo te ensinar a **criar um Codelabs** próprio, para engajar melhor a sua equipe ou comunidade.
<br />

## Ferramentas utilizadas no Windows
### Pré-Requisitos
1. [Go](https://go.dev/dl/)
1. [Node.js e npm](https://nodejs.org/en/download/)
1. [claat](https://github.com/googlecodelabs/tools/tree/main/claat#install)

<br />
### Instalação do Go no Windows
Baixe a última versão do Go no Windows (1.17.8 no momento da criação deste tutorial) e instale como qualquer outro programa normal.

![Microsoft Windows
Windows 7 or later, Intel 64-bit processor
go1.17.8.windows-amd64.msi](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/alg5ky1lrznalzmk9xhy.png)

Para verificar se está instalado, basta **digitar no Terminal:**

```bash
go version
```

e verificar se a **resposta é a versão do Go.**
<br />

### Instalação do Node.Js no Windows
Baixe a última versão do Node.js (16.14.0 no momento da criação deste tutorial) e instale como qualquer outro programa normal.
![Node.Js](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mc4i6q3qi89p0dffq2g5.png)

Para verificar se está instalado, basta **digitar no Terminal:**

```bash
Node --version 
```

e verificar se a **resposta é a versão do Node.js que você instalou.** 
<br />
Para verificar a instalação do **npm, digite no Terminal:**

```bash
npm -v
```

e verifique se a **reposta é a versão equivalente do npm para aquele Node.js.**
<br />

### Instalação do claat no Windows
Abra o terminal de sua preferência e digite:

```bash
go install github.com/googlecodelabs/tools/claat@latest
```

Uma vez instalado digite `claat -h` no terminal e verifique se a resposta são os comandos do claat.
<br />

## Gerando o HTML
O codelabs transforma um arquivo de **markdown** em um guia interativo, onde cada passo é representado pelo título do arquivo. Ou seja, basta criar um arquivo .md na sua pasta de preferencia.

Uma vez gerado, basta inserir um cabeçalho no arquivo de markdown como no exemplo abaixo e escrever sua documentação ou guia como qualquer outro arquivo .md convencional, lembrando que o **Codelabs irá nomear o arquivo de acordo com o "id" do cabeçalho, o nome do guia de acordo com o "H1" e as páginas serão divididas de acordo com o "H2" do .md**

> author: John Vitor Constant de Oliveira Lourenço
> summary: Documentação de APIs com o Readme
> id: como-criar-um-codelabs
> categories: codelabs,markdown
> environments: Web
> status: Published
> feedback link: um link onde os usuários podem dar o feedback (talvez o repositório git)
> analytics account: Google Analytics ID


O arquivo de markdown utilizado neste guia pode ser obtido [aqui](https://raw.githubusercontent.com/johnvitorconstant/como-criar-um-codelabs/main/como-criar-um-codelabs.md).

Uma vez criado o arquivo .md, basta navegar até a pasta do arquivo pelo Terminal: 

```bash
cd "C:\Workbench\Sites\Como criar um codelabs"
```
e rodar o comando do claat:

```bash
claat export como-criar-um-codelabs.md
```

Finalizando, ele irá criar uma pasta com o arquivo .html já no formato de Codelabs.
Tanto o .md quanto o html gerado neste guia pode ser acessado [aqui. ](https://github.com/johnvitorconstant/como-criar-um-codelabs)

## Fazendo deploy da aplicação
Em breve