Conceitos do Docsbook: espaço de trabalho, equilíbrio do projeto, indexação

Cada termo usado na interface e na documentação do Docsbook, definido uma única vez. Cada entrada apresenta uma definição em uma frase e, em seguida, informa onde você encontra o termo e o que ele afeta. Os termos são agrupados, e os grupos são organizados em ordem alfabética internamente.

O site e seu conteúdo#

Espaço de trabalho#

Um espaço de trabalho é um site de documentação e suas configurações, baseado em um repositório de arquivos Markdown. O repositório é seu no GitHub ou um que o Docsbook hospeda para você quando você começa a partir de uma varredura de site ou de um briefing escrito.

Um espaço de trabalho é responsável por seu endereço, sua aparência, suas configurações de idioma, suas análises e seu saldo. O painel de administração e as telas de cobrança do Docsbook chamam o mesmo objeto de projeto; as duas palavras significam a mesma coisa.

Rascunho#

Um rascunho é um site de documentação gerado que ainda não foi publicado. O Docsbook cria um a partir da sua fonte antes de você ter uma conta.

Um rascunho de uma verificação de site ou de um briefing escrito permanece no seu navegador até que você o publique. Um rascunho é aberto no mesmo painel de administração que um espaço de trabalho publicado, para que a marca, o layout e o SEO possam ser definidos antes de iniciar sessão.

Página#

Uma página é um arquivo Markdown no repositório do espaço de trabalho, disponibilizado em seu próprio URL. Os nomes de arquivos e pastas determinam o URL e a posição na árvore de navegação.

As extensões .md e .markdown são lidas. Arquivos em outros formatos — .txt, .rst — não são transformados em páginas.

Árvore de navegação#

A árvore de navegação é a barra lateral que o Docsbook cria a partir da estrutura de pastas do seu repositório. Uma pasta se torna um grupo; um arquivo se torna uma entrada dentro dele.

README.md na raiz de uma pasta se torna a página inicial dessa pasta. Você não precisa escrever um arquivo de navegação: mover um arquivo no repositório o move na barra lateral.

Sumário#

O sumário é o índice por página que o Docsbook cria a partir dos títulos dessa página, exibido à direita do conteúdo. Clicar em um título rola a página até ele.

O sumário é gerado a partir dos títulos H2 e inferiores, portanto, pular um nível de título deixa uma lacuna nele.

Widget de conteúdo#

Um widget de conteúdo é uma região de uma página Markdown que o Docsbook renderiza como um bloco rico — uma grade de cartões, um acordeão, etapas numeradas ou uma chamada para ação — marcada com dois comentários HTML.

Os comentários ficam invisíveis em qualquer outro leitor de Markdown, portanto o mesmo arquivo continua sendo exibido corretamente no GitHub. Um nome de widget desconhecido é convertido em Markdown comum; nada é ocultado. Consulte Widgets de conteúdo.

Como o conteúdo entra e permanece atualizado#

Indexação#

Indexação é o processo que o Docsbook executa sobre seu Markdown para criar tudo o que o site precisa: o índice de pesquisa, a árvore de navegação, o sumário de cada página, o grafo de links e os embeddings que o chat de IA consulta.

A indexação é executada quando um workspace é criado e novamente quando o Docsbook detecta conteúdo alterado. Uma página que não foi indexada não pode ser encontrada pela pesquisa nem citada pelo chat.

Sincronização com o GitHub#

Sincronização com o GitHub é como um site Docsbook se mantém alinhado com seu repositório: o Docsbook verifica se há novos commits no GitHub quando o site é visitado e reindexa o que mudou. Não há webhook para configurar nem etapa de compilação para aguardar.

Sincronizados: novos arquivos .md, edições de texto, exclusões, renomeações e novas pastas. Não sincronizados: histórico de commits, informações de branches, comentários no código e arquivos em outros formatos.

Fonte da verdade#

Uma fonte da verdade é um repositório ou site que você conectou a um espaço de trabalho para que um agente que escreve sua documentação leia fatos dele em vez de recuperá-los da memória. Cada fonte conectada inclui a própria observação do proprietário sobre o motivo pelo qual ela está conectada.

As fontes são entradas somente leitura. Elas são separadas do repositório a partir do qual o site é criado. Consulte Fontes conectadas.

Editor web#

O editor web é o editor no navegador do Docsbook para os arquivos Markdown do workspace. Salvar cria um commit no repositório a partir do qual o site é compilado.

As edições feitas no editor web, no GitHub e por um agente via MCP são registradas no mesmo repositório, portanto há um único histórico, em vez de dois.

Dinheiro e medição#

Saldo do projeto#

Um saldo do projeto é o dinheiro associado a um workspace, gasto no trabalho de IA realizado para esse workspace. Todo projeto novo é criado com um saldo de $1.00, mais $5.00 que o proprietário pode resgatar quando o projeto tiver 3 minutos de existência, e recebe recargas posteriormente na tela de cobrança.

Os saldos são por projeto, não por conta: o esgotamento de um projeto não interrompe outro. Consulte Preços.

Recarga#

Uma recarga é um pagamento para o saldo de um projeto, no valor que você definir. A menor recarga individual é de $20.00 e a maior é de $5,000.00.

As recargas não expiram, e nenhum saldo é recarregado automaticamente. É possível configurar um pagamento mensal recorrente na tela de cobrança; ele recarrega o mesmo saldo todos os meses.

Trabalho medido#

Trabalho medido é o trabalho que consome o saldo de um projeto. Existem exatamente quatro tipos, e cada um é uma linha em Gastos por fonte no cartão de Limites do projeto:

• Leitores (Chat de IA) — uma resposta de IA fornecida a um leitor da documentação publicada.
• Administrador & Agente de IA — uma execução de agente, incluindo chamadas de ferramentas MCP medidas.
• Traduções por IA — tradução de uma página para outro idioma.
• Índice semântico — criação dos embeddings dos quais o chat de IA recupera informações.

Nada mais é medido: hospedagem, um domínio personalizado e seu certificado TLS, leitores, editores, sincronização com o GitHub, pesquisa de texto completo, marca, análises e chamadas de leitura MCP não têm custo por uso. Qualquer uma das quatro fontes pode ter um limite definido para o ciclo no cartão de Limites, e um limite de US$ 0 desativa essa fonte.

Markup#

Markup é a porcentagem que o Docsbook adiciona ao preço real cobrado pelo provedor de IA pelo modelo que respondeu — atualmente 900%. O modelo, sua tarifa por 1 milhão de tokens e o markup são exibidos no painel.

Usar sua própria chave de API do provedor remove essa cobrança: você paga diretamente ao provedor, e o Docsbook não cobra nada de você por esse uso.

Quem pode ler o site#

Site público#

Um site público é o padrão: qualquer pessoa com o link pode acessá-lo, incluindo pessoas sem uma conta do GitHub e rastreadores de mecanismos de pesquisa. A visibilidade do próprio repositório não altera isso — o Docsbook lê o repositório e, em seguida, disponibiliza as páginas que criou.

O acesso público é o que torna o site indexável pelo Google e citável por assistentes de IA.

Site privado#

Um site privado exibe uma tela de desbloqueio em vez do seu conteúdo para todos, exceto o proprietário, protegido por uma senha compartilhada ou pelo seu próprio provedor de identidade SSO. A estrutura, as páginas e o índice de pesquisa permanecem ocultos até que um leitor o desbloqueie.

O proprietário sempre tem acesso total, independentemente da visibilidade. Consulte Documentação privada: senha e SSO.

Domínio personalizado#

Um domínio personalizado é o seu próprio nome de host — docs.yourcompany.com — que atende ao workspace em vez de docsbook.io/{owner}/{repo}. Você adiciona um registro CNAME e o Docsbook provisiona o certificado TLS.

O endereço docsbook.io continua funcionando depois que um domínio personalizado é associado. Consulte Configuração de domínio personalizado.

Superfícies que as máquinas leem#

llms.txt#

llms.txt é um índice em texto simples de um site Docsbook, disponibilizado na raiz do site para agentes de IA que procuram um. Ele lista as páginas e o conteúdo de cada uma.

O Docsbook gera esse arquivo a partir do conteúdo indexado, portanto ele não fica desatualizado separadamente do site. Consulte llms.txt.

servidor MCP#

O servidor MCP é o endpoint do Model Context Protocol do Docsbook em https://docsbook.io/api/mcp/server, expondo 140 ferramentas que permitem que um agente de IA pergunte ao agente docsbook_expert o que fazer e receba instruções, leia sua documentação, pesquise nela, altere configurações e faça commit das páginas. A autenticação é Bearer usando OAuth 2.0 com PKCE.

As chamadas de descoberta nunca são contabilizadas; as outras chamadas consomem o saldo do projeto. Consulte o servidor MCP e a referência das ferramentas MCP.

Widget flutuante#

O widget flutuante é o menu de controle no canto inferior direito da sua própria documentação publicada, visível apenas para você enquanto estiver conectado. Os leitores nunca o veem.

Ele alterna entre chat, repositório e modo, abre as configurações e encerra sua sessão.

Relacionados#

• Visão geral — como essas partes se encaixam, de ponta a ponta
• Início rápido — o tutorial que usa estes termos na ordem
• Referência das ferramentas MCP — cada ferramenta, seus parâmetros e sua classe de preço
• Preços — o que é medido e pelo que o saldo de um projeto paga