Migrando do GitBook para o Docsbook: um guia passo a passo

Você chegou ao ponto em que a taxa por usuário do GitBook cresce mais rápido do que a documentação. Ou o preço do complemento de IA. Ou você percebeu que está pagando uma conta anual por um site de documentação que não indexa bem. Este é o guia prático de migração.

A maioria das equipes completa isso em menos de três horas. A parte cara são os redirecionamentos.

Resumo#

1. Exporte o conteúdo do GitBook como markdown
2. Envie para um novo repositório no GitHub
3. Conecte o Docsbook a esse repositório (5 segundos)
4. Verifique o site em docsbook.io/yourorg/yourrepo
5. Conecte seu domínio personalizado docs.yourcompany.com ao Docsbook
6. Configure redirecionamentos dos antigos caminhos do GitBook
7. Atualize os links internos em todo o seu site

Passo 1: Exportar do GitBook#

O GitBook suporta exportação em markdown através das configurações do espaço:

• Abra seu espaço no GitBook
• Configurações → Sincronizar com Git → "Sincronizar GitBook com o provedor Git"
• Escolha GitHub, selecione um novo repositório privado ou público
• O GitBook sincroniza seu conteúdo como markdown com frontmatter

Alternativa (sem Sincronização Git): use a opção "Exportar para Markdown" no menu do espaço e descompacte o resultado localmente.

A estrutura de pastas que o GitBook exporta:

README.md
SUMMARY.md
docs/
  introduction.md
  guides/
    quick-start.md
  api/
    auth.md

Passo 2: Ajustar para as convenções do Docsbook#

Duas pequenas diferenças a serem tratadas:

SUMMARY.md é opcional no Docsbook#

GitBook usa SUMMARY.md como a fonte de navegação. O Docsbook constrói a navegação a partir da sua estrutura de pastas e frontmatter title automaticamente.

Você pode manter SUMMARY.md (o Docsbook ignora) ou excluí-lo. A maioria das equipes o exclui.

Frontmatter#

Frontmatter do GitBook:

---
description: How to authenticate
---

Docsbook lê o mesmo campo description mais title opcionais. Se title estiver ausente, o primeiro H1 é usado.

Um script de migração simples:

find . -name "*.md" -not -path "./.git/*" -exec \
  sed -i.bak '1,/^---$/ s/^description:/description:/' {} \;

(Nenhuma alteração necessária na maioria dos casos — Frontmatter do GitBook e Docsbook são compatíveis.)

Passo 3: Conectar Docsbook#

• Vá para docsbook.io
• Faça login com o GitHub
• Cole github.com/yourorg/yourrepo
• Site ao vivo em docsbook.io/yourorg/yourrepo em 5 segundos

Se seu repositório tiver a pasta docs/, o Docsbook a utiliza. Se sua documentação estiver na raiz, isso também funciona.

Passo 4: Domínio personalizado#

Docsbook serve docs.yourcompany.com com SSL automático.

No painel do Docsbook:

• Configurações → Domínio
• Insira docs.yourcompany.com
• Atualize seu DNS: CNAME docs → cname.vercel-dns.com
• SSL é automático e gratuito

Passo 5: Os redirecionamentos#

Este é o único passo que importa para SEO. Os URLs do GitBook parecem:

docs.yourcompany.com/v/1.0/api/authentication

URLs do Docsbook:

docs.yourcompany.com/api/authentication

Você tem duas opções:

Opção A: redirecionar no nível DNS/CDN#

Se você tiver Cloudflare na frente do seu domínio, adicione regras de página:

docs.yourcompany.com/v/*/api/* → docs.yourcompany.com/api/$2 [301]

Opção B: redirecionar via Docsbook#

Adicione um arquivo _redirects (se sua pilha suportar) na raiz do seu repositório:

/v/1.0/api/auth /api/auth 301
/v/1.0/api/webhooks /api/webhooks 301

Um 301 preserva a autoridade de SEO. Um 302 não preserva — use 301.

Passo 6: Atualizar referências internas#

Pesquise e substitua em todo o seu código:

grep -rl "docs.yourcompany.com/v/" . | xargs sed -i.bak 's|docs.yourcompany.com/v/[0-9.]*/|docs.yourcompany.com/|g'

Atualizar:

• O link do rodapé do seu aplicativo
• Seu site de marketing
• Seus links README no GitHub
• As respostas salvas da sua equipe de suporte

Passo 7: Verifique a superfície da IA#

Docsbook gera llms.txt, llms-full.txt, JSON-LD e sitemap automaticamente. Verifique:

curl https://docs.yourcompany.com/llms.txt | head -20
curl https://docs.yourcompany.com/sitemap.xml | head -10

Veja llms.txt: o guia completo para o que esperar.

O que melhora#

O que pode quebrar#

• Blocos específicos do GitBook — seções colapsáveis, blocos de dica, abas. O Docsbook suporta markdown padrão + blocos específicos do Docsbook. A maioria das dicas do GitBook se reescreve de forma limpa para > [!NOTE] chamadas.
• Integração OpenAPI personalizada — O GitBook tem seu renderizador de referência de API. O Docsbook renderiza OpenAPI através de suas ferramentas existentes ou links externos.
• Histórico de chat do GitBook AI — não é transferido. O chat começa do zero com seu novo conteúdo.

Cronograma#

Na nossa experiência ajudando equipes a migrar:

• Fundador solo, ~50 páginas: 1 hora
• Pequena startup, ~200 páginas: 3 horas
• Empresa em estágio médio, ~1000 páginas, domínio personalizado: meio dia

A parte cara é socializar a mudança de URL internamente e atualizar as respostas salvas na sua ferramenta de suporte.

Comece grátis — sem cartão de crédito

Próximos passos#

• GitBook vs Docsbook — a comparação recurso por recurso por trás dessa mudança
• Domínio personalizado para documentação — a parte de DNS e SSL do passo 4
• Guia de SEO para documentação — como manter classificações através da mudança de URL