Gerencie seu site de documentação

Este guia aborda o que você faz depois que seu site está no ar: alterar páginas, desfazer uma alteração, decidir quem pode lê-lo e diagnosticar um site que não incorporou seu commit mais recente. Se você ainda não publicou um site, comece com Crie seu primeiro site de documentação.

Abrir o widget de gerenciamento#

Faça login e abra seu próprio site. Um widget de gerenciamento aparece no canto inferior direito:

+----------------------+
| Your name            |
|                      |
| Select chat        > |
| Select repo        > |
| Select mode        > |
|                      |
| Settings             |
| Sign out             |
+----------------------+

Clique no seu avatar ou em Configurações para abrir o painel de configurações. Tudo nesta página que diz "Configurações" começa aqui.

Os leitores nunca veem este widget. Visitantes que não fizeram login recebem sua documentação, seu design e seu conteúdo, sem nenhum dos controles.

O que você pode configurar em Configurações#

Atualizar uma página do GitHub#

1. Abra seu repositório no github.com.
2. Abra o arquivo Markdown e clique no ícone de lápis.
3. Faça sua alteração e clique em Confirmar alterações.

Seu site obtém o commit automaticamente. Nada para reimplantar.

Atualize páginas do seu computador com git#

Use isto quando estiver alterando vários arquivos de uma só vez e quiser revisá-los juntos.

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO

Edite os arquivos no seu editor e publique-os:

git add docs/
git commit -m "Update the installation guide"
git push origin main

Excluir uma página segue o mesmo processo: exclua o arquivo, faça commit e push. A página desaparece do site e da barra lateral.

Edite uma página sem sair do navegador#

Para uma pequena correção, você não precisa do GitHub nem de uma cópia local — edite a página que está lendo.

1. Abra o projeto no chat do Docsbook AI com a pré-visualização ao lado (visualização dividida).
2. Alterne a barra acima da pré-visualização de Pré-visualização para Editar.
3. Clique no bloco que deseja alterar.

O painel que é aberto pode reescrever o bloco com IA, editar o texto diretamente, encurtá-lo ou expandi-lo, transformá-lo em um widget de conteúdo ou removê-lo. Arraste um bloco pela alça para movê-lo; a nova ordem é pré-visualizada até você clicar em Salvar ou Reverter.

Para adicionar algo em vez de alterá-lo, mova o ponteiro para a junção entre dois blocos. Um botão de adição aparece e oferece um parágrafo, um título, uma lista, um bloco de código, uma citação, um destaque, uma tabela ou um widget. Adicionar uma página, na parte inferior da barra lateral, cria uma página inteira a partir de um título, uma pasta e uma nota opcional sobre o que ela deve abordar.

Cada uma dessas ações é registrada no seu repositório como qualquer outra alteração, portanto sua fonte continua sendo a única fonte de verdade. Reescrever um bloco com IA chama um modelo e é cobrado do saldo do projeto; editar o texto por conta própria não é.

Desfazer uma alteração publicada#

Qualquer alteração publicada pelo assistente pode ser desfeita pelo chat, sem abrir o GitHub.

• Imediatamente: pressione a seta de desfazer no cartão exibido pelo assistente após a publicação ("2 arquivos atualizados").
• Mais tarde: abra o ícone de relógio no cabeçalho do chat. Ele lista as alterações recentes do projeto com os arquivos afetados por cada uma e uma opção de desfazer ao lado de cada entrada.

Esse histórico é o histórico real de publicação do seu repositório, portanto também lista alterações feitas em uma sessão anterior, por um colega de equipe ou diretamente no GitHub. Todas podem ser desfeitas da mesma maneira.

Uma ação de desfazer é um novo commit que restaura os arquivos, não uma reescrita do histórico. Ela aparece na lista como uma entrada própria marcada como Desfazer, também pode ser desfeita e nunca descarta os commits de outras pessoas. Se não for possível ler novamente uma versão anterior de um arquivo, isso será informado como ignorado em vez de ser presumido.

Pergunte ao assistente o que melhorar#

Pergunte ao assistente o que corrigir — "o que devo corrigir primeiro", "torne isto encontrável nas pesquisas", "estas páginas parecem superficiais" — e a resposta virá como uma lista para você marcar, não como um texto que precisaria executar manualmente.

Cada linha representa uma alteração concreta em uma das suas páginas reais: o que ela altera, por que é útil e qual página afeta. Algumas linhas correspondem a uma configuração, e abrem o cartão que a ativa. Nenhuma linha vem marcada inicialmente. Marque as linhas desejadas, pressione Aplicar uma vez, e todas as linhas marcadas serão concluídas de uma só vez. As linhas não marcadas nunca são gravadas.

A lista não é baseada em suposições: o assistente lê a habilidade de documentação que abrange o que você pediu — pesquisa e indexação, tom, acessibilidade, tradução — verifica o que consegue medir sobre o seu site, verifica quais cartões de configurações existem e faz recomendações com base no que foi encontrado. Ele informa qual habilidade aplicou.

O que Aplicar faz depende do modo automático:

A geração da lista e a reescrita das páginas chamam um modelo de IA, portanto ambas são debitadas do saldo do projeto.

Entenda a ordem da barra lateral#

O Docsbook lê os nomes dos seus arquivos para ordenar a barra lateral:

• As páginas que iniciam a leitura — README, introduction, getting-started, quick-start, installation, setup — são listadas primeiro.
• As páginas para consultar informações — reference, api, changelog, faq, troubleshooting — são listadas por último.
• Todo o restante fica em ordem alfabética entre elas. As pastas são classificadas pelos próprios nomes da mesma forma.

Os prefixos numéricos, portanto, continuam funcionando: 1-basics.md é ordenado antes de 2-intermediate.md em ordem alfabética, e o número é ignorado quando o Docsbook verifica o nome em relação às duas listas acima.

Se nenhuma das suas páginas corresponder a uma das listas, a barra lateral ficará em ordem alfabética simples. Renomeie um arquivo para movê-lo.

Organize arquivos em pastas#

A barra lateral espelha sua estrutura de pastas, portanto, a estrutura é a navegação. Agrupe por tópico:

docs/
├── README.md
├── getting-started.md
├── api/
│   ├── overview.md
│   ├── auth.md
│   └── endpoints.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

Agrupar por tópico é melhor do que agrupar por dificuldade (1-basics.md, 2-advanced.md), porque um leitor chega de um mecanismo de busca procurando um assunto, não um nível.

Link entre páginas#

Escreva links Markdown relativos comuns. O Docsbook os converte em URLs do site quando os publica.

[Set up a custom domain](/docsbook-io/docs/guides/advanced/custom-domain)
[Create your first site](/docsbook-io/docs/guides/getting-started/creating-docs)
[Frequently asked questions](/docsbook-io/docs/faq)

Crie um link para um título na mesma página usando sua âncora:

[Jump to the sidebar order](#understand-the-sidebar-order)

A âncora é o texto do título em letras minúsculas, com os espaços substituídos por hífens, portanto o título precisa existir para que o link direcione ao local correto.

Adicionar imagens#

1. Coloque o arquivo de imagem no seu repositório ao lado da página, por exemplo, em uma pasta images/.
2. Faça commit dele.
3. Faça referência a ele com um caminho relativo e descreva o que ele mostra:

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

PNG, JPG, GIF e WebP são renderizados. Escreva um texto alternativo real em todas as imagens que transmitem informações — é o que um leitor de tela anuncia, o que um mecanismo de busca indexa e o que um leitor vê quando o arquivo não é carregado.

Controle quem pode ler sua documentação#

Por padrão, um site Docsbook é público: qualquer pessoa com o link pode acessá-lo, os rastreadores de mecanismos de pesquisa o indexam e não é necessária uma conta do GitHub. Isso se aplica mesmo quando o repositório de origem é privado.

Para fechá-lo, alterne o workspace para privado em Configurações → Privacidade & Acesso. Então, o leitor precisa desbloqueá-lo com uma senha compartilhada ou entrar por meio do seu próprio provedor de identidade OIDC — inclusive os rastreadores. Você, como proprietário, sempre tem acesso. Configuração completa: Restrinja quem pode ler seu site de documentação.

Trabalhe com outras pessoas#

Por meio do GitHub. Adicione-as como colaboradoras no repositório. Elas editam arquivos ou abrem pull requests, e o site é atualizado quando uma alteração chega à sua ramificação padrão. Este é o caminho para quem já trabalha no repositório.

Por meio do chat de IA. Pressione Convidar na barra de ferramentas do chat e envie um convite por e-mail ou um link. As colaboradoras entram na mesma sessão ao vivo, portanto não precisam de uma conta do GitHub. O trabalho delas utiliza o mesmo saldo do projeto que o seu.

Corrigir um site que não foi atualizado#

Siga estas etapas na ordem.

1. Confirme que o commit chegou ao GitHub. Abra o repositório e procure-o. Se ele não estiver lá, nunca foi enviado.
2. Recarregue ignorando o cache do navegador. Ctrl+F5 ou Cmd+Shift+R no macOS. Uma janela privada é a maneira mais rápida de descartar o cache.
3. Aguarde alguns minutos. A publicação não é instantânea; o Docsbook verifica o repositório periodicamente, e não a cada tecla pressionada.
4. Verifique a extensão do arquivo. Somente arquivos .md são publicados.
5. Verifique o nome do arquivo. Letras latinas, dígitos e hifens são seguros; outros caracteres podem não gerar uma URL.

Se algumas páginas foram atualizadas e outras não, quase sempre o problema é o cache do navegador, e não a sincronização — uma atualização parcial não é um estado que o Docsbook publica.

Versionamento#

O Docsbook disponibiliza uma versão da sua documentação: o estado atual da sua branch. Atualmente, não há suporte para várias versões publicadas lado a lado.

Se você precisar delas agora, mantenha as versões em branches separadas (docs/v1, docs/v2) ou em repositórios separados e conecte aquela que deseja publicar.

Veja quem está lendo#

Abra o Float Widget → Analytics. Visualizações, visitantes, páginas principais, sites de referência e consultas de pesquisa são relatados por página, para que você possa ver quais páginas atraem tráfego e quais permanecem sem leitura.

Dois relatórios respondem à maioria das perguntas sobre uma página: análise da web para tráfego e feedback da página para saber se os leitores que chegaram encontraram o que precisavam.

Excluir um espaço de trabalho#

Configurações → Excluir espaço de trabalho remove o site de documentação e todas as configurações dele. Essa ação não pode ser desfeita.

Seu repositório do GitHub permanece intacto. O markdown continua onde sempre esteve, portanto excluir um espaço de trabalho remove a configuração, não o conteúdo.

Próximos passos#

• Configure um domínio personalizado — disponibilize a documentação em um endereço que você possui.
• Traduza sua documentação — 15 idiomas, cada um indexado separadamente.
• O que o Docsbook inclui e o que custa dinheiro — quais ações consomem o saldo do projeto.
• Perguntas frequentes — as perguntas que os leitores fazem antes de se comprometerem.