Crie seu primeiro site de documentação

Neste tutorial, você publica um site de documentação a partir de um repositório do GitHub e altera uma página nele. Você não precisa ter experiência em programação nem instalar nada: todas as etapas acontecem em um navegador.

O que você terá ao final: um site de documentação disponível em docsbook.io/YOUR-USERNAME/docs e uma página dele que você editou.

Antes de começar#

Você precisa de duas coisas:

• Um navegador e uma conexão com a internet. Qualquer sistema operacional funciona.
• Uma conta do GitHub. É gratuita. A etapa 1 cria uma se você não tiver uma.

O que é o GitHub? O GitHub é um site onde as pessoas armazenam e compartilham arquivos de texto. Pense no Google Drive, criado para documentação e código. O Docsbook lê seus arquivos do GitHub e os publica como um site de documentação.

Etapa 1: crie uma conta no GitHub#

Ignore esta etapa se você já tiver uma conta.

1. Acesse github.com.
2. Clique em Cadastre-se no canto superior direito.
3. Insira seu endereço de e-mail e escolha uma senha.
4. Escolha um nome de usuário. Ele aparece na URL da sua documentação, como em docsbook.io/your-username/your-repo.
5. Confirme o código de verificação que o GitHub enviará para você por e-mail.

Etapa 2: faça um fork do repositório de exemplo#

Um repositório — "repo", para abreviar — é uma pasta no GitHub que contém seus arquivos de documentação. Um repositório publica um site de documentação.

Em vez de começar com um repositório vazio, copie o repositório de exemplo do Docsbook. Copiar o repositório de outra pessoa é chamado de fork, e sua cópia é independente: o que você alterar nunca afetará o original.

1. Acesse github.com/docsbook-io/docs.

   

2. Clique em Fork no canto superior direito.

3. Deixe todas as configurações como estão e clique em Create fork.

   

4. O GitHub abre seu novo repositório em github.com/YOUR-USERNAME/docs.

   

Agora você tem um repositório contendo uma documentação de exemplo, pronto para ser publicado.

Etapa 3: conecte o repositório ao Docsbook#

1. Acesse docsbook.io/connect.

   

2. Escolha um método de login — GitHub, Google, Apple ou um código de uso único enviado por e-mail — e conclua o processo.

3. Se você fez login com o Google, a Apple ou por e-mail, o Docsbook solicitará acesso ao GitHub. Clique em Authorize docsbook.

   O Docsbook lê os arquivos do seu repositório. Ele não pode modificar nem excluir nada no seu repositório, a menos que você solicite isso.

4. Encontre na lista o repositório que você bifurcou e clique nele.

   

5. O Docsbook cria seu site e redireciona você para ele.

Sua documentação está disponível em:

docsbook.io/YOUR-GITHUB-USERNAME/docs

Abra-a e navegue pela barra lateral. Cada página exibida é um arquivo Markdown no repositório que você bifurcou.

Etapa 4: edite uma página no GitHub#

1. Abra seu repositório em github.com/YOUR-USERNAME/docs.

2. Clique no arquivo que deseja alterar — comece com README.md.

   

3. Clique no ícone de lápis próximo ao canto superior direito do arquivo.

   

4. Altere uma frase. O arquivo é escrito em Markdown: **bold** é renderizado em negrito, # Heading é renderizado como um título grande. A referência de sintaxe do markdown no final desta página aborda o restante.

   

5. Role para baixo até Confirmar alterações.

6. Escreva uma breve observação descrevendo o que você alterou, como "Atualizar a introdução".

7. Clique em Confirmar alterações.

   

Etapa 5: veja a alteração no seu site#

Volte ao seu site do Docsbook e recarregue a página que você editou. Sua nova frase está lá.

Esse é o ciclo completo: faça commit no GitHub, e o site publicado acompanha. Você concluiu o tutorial.

Adicionar e excluir páginas#

Adicionar uma página segue o mesmo processo, com um botão diferente.

Adicionar uma página:

1. Abra seu repositório e clique em Add file → Create new file.

   

2. Em Name your file, digite o caminho e o nome do arquivo, como guides/installation.md. Digitar um / cria a pasta.

   

3. Escreva o conteúdo e clique em Commit new file.

A página aparece sozinha na barra lateral do Docsbook.

Excluir uma página:

1. Abra o arquivo no seu repositório.

2. Clique no menu ⋯ próximo ao canto superior direito.

   

3. Clique em Delete file e depois em Commit changes.

Outras formas de fazer isso#

O tutorial acima usa o caminho que funciona sem nada instalado. Existem três alternativas depois que você passa do primeiro site.

Comece por um repositório vazio em vez de fazer um fork. Acesse github.com/new, dê ao repositório um nome curto sem espaços, selecione Público, marque Adicionar um arquivo README e clique em Criar repositório. Em seguida, conecte-o exatamente como na etapa 3.

Escreva páginas com um assistente de programação de IA. O Claude Code lê, cria e edita arquivos por meio de uma conversa, o que é mais rápido quando você está produzindo muitas páginas de uma só vez. Instale-o em claude.ai/code, peça para ele clonar seu repositório e descreva o que você quer — "crie guides/installation.md com seções para requisitos, instalação e primeiro login". Quando terminar, diga para ele fazer commit e push, e seu site será atualizado.

Edite na própria página publicada. Depois que seu site estiver conectado, você poderá alterar um bloco na página que está lendo, dentro do chat do Docsbook AI, sem o GitHub e sem precisar instalar nada. Veja como editar na página ao vivo.

Referência: sintaxe Markdown#

Markdown é um conjunto de símbolos que controlam a formatação. Estes são os utilizados na documentação.

Texto#

Títulos, listas e links#

# Large heading (page title)
## Medium heading (section)
### Small heading (sub-section)
 
- First item
- Second item
  - Nested item, indented by two spaces
 
1. First step
2. Second step
 
[Link to an external site](https://example.com)
[Link to another page in your docs](/docsbook-io/docs/guides/getting-started/managing-docs)

Imagens e blocos de código#

![Fork dialog with the Create fork button highlighted](https://raw.githubusercontent.com/docsbook-io/docs/main/guides/getting-started/images/fork-dialog.png)

Delimite um bloco de código com três crases e nomeie a linguagem para que ele receba realce de sintaxe:

```javascript
console.log("Hello!")
```

Destaques#

> This is a note or an important callout.

Referência: como seus arquivos se tornam páginas#

O Docsbook cria a barra lateral a partir dos nomes dos seus arquivos e pastas. Não há nada para configurar.

Disso resultam três regras:

• Os nomes de arquivos e pastas tornam-se títulos de páginas, com hífens substituídos por espaços.
• README.md dentro de uma pasta torna-se a página de índice dessa pasta.
• Nomes em minúsculas com hífens produzem URLs legíveis: getting-started.md torna-se /getting-started.

Para saber o que determina a ordem dessas páginas, consulte Gerencie seu site de documentação.

Próximos passos#

• Gerencie seu site de documentação — atualize o conteúdo, controle o acesso e corrija um site que não foi atualizado.
• Configure um domínio personalizado — disponibilize a documentação em docs.yourcompany.com.
• Ative a pesquisa de texto completo — permita que os leitores encontrem uma página por palavra-chave.