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.
Objetivo
Google Developers Codelabs é 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.
Ferramentas utilizadas no Windows
Pré-Requisitos
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.
Para verificar se está instalado, basta digitar no Terminal:
go version
e verificar se a resposta é a versão do Go.
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.
Para verificar se está instalado, basta digitar no Terminal:
Node --version
e verificar se a resposta é a versão do Node.js que você instalou.
Para verificar a instalação do npm, digite no Terminal:
npm -v
e verifique se a reposta é a versão equivalente do npm para aquele Node.js.
Instalação do claat no Windows
Abra o terminal de sua preferência e digite:
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.
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.
Uma vez criado o arquivo .md, basta navegar até a pasta do arquivo pelo Terminal:
cd "C:\Workbench\Sites\Como criar um codelabs"
e rodar o comando do claat:
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.
Fazendo deploy da aplicação
Em breve
Top comments (0)