Docsbook
Visão geral

Migrando do Docusaurus para o Docsbook, passo a passo

O Docusaurus é ótimo até que a próxima migração importante chegue e você passe um sprint nela em vez de lançar o produto. Este guia percorre o caminho de migração realista.

Nós fazemos o Docsbook. Também iremos te dizer quando a migração não vale a pena.

Quando você não deve migrar#

Ignore esta migração se:

  • Seu site Docusaurus usa incorporações pesadas de componentes React (demonstrações interativas, plugins personalizados). Docsbook é focado em markdown.
  • Você tem um engenheiro de documentação dedicado cujo trabalho inclui parcialmente Docusaurus. A plataforma tem verdadeiras forças em suas mãos.
  • Você precisa de um tema React profundamente personalizado. Docsbook oferece tokens de cor, fontes, alternâncias de layout, configuração de cabeçalho/rodapé — não uma troca completa de tema.

Se algum desses se aplicar, permaneça no Docusaurus e leia o restante deste guia mais tarde.

Resumo#

  1. Remover a sintaxe específica do MDX para markdown padrão
  2. Enviar para um repositório GitHub (você já tem um)
  3. Conectar o Docsbook
  4. Conectar domínio personalizado
  5. Redirecionar portas
  6. Eliminar o pipeline CI e a conta de hospedagem

Passo 1: MDX para markdown#

Docusaurus usa MDX, que é markdown + JSX. Docsbook usa markdown padrão com extensões.

Três classes de MDX que precisam de tratamento:

Importações e componentes React#

import Foo from '@site/src/components/Foo';
 
<Foo />

Soluções:

  • Para visuais estáticos: substitua por uma imagem hospedada e um link para uma demonstração ao vivo
  • Para elementos interativos: vincule ao seu aplicativo
  • Para abas/admoestações: use os blocos nativos do Docsbook (veja abaixo)

Admoestações#

Docusaurus:

:::note Title
Content
:::

Docsbook (markdown com sabor GitHub):

> [!NOTE]
> Content

Buscar e substituir:

find . -name "*.mdx" -exec rename 's/\.mdx$/\.md/' {} \;
find . -name "*.md" -exec sed -i.bak -E 's/:::note/> [!NOTE]/g; s/:::tip/> [!TIP]/g; s/:::warning/> [!WARNING]/g; s/:::caution/> [!CAUTION]/g; s/:::info/> [!NOTE]/g; s/^:::$//' {} \;

Guias e grupos de código#

Docsbook suporta guias através de uma sintaxe padrão:

<Tabs>
  <Tab title="npm">npm install foo</Tab>
  <Tab title="pnpm">pnpm add foo</Tab>
</Tabs>

A maioria das guias do Docusaurus traduz-se um a um.

Passo 2: Barra lateral e navegação#

Docusaurus usa sidebars.js para definir a navegação. O Docsbook constrói a navegação a partir da sua estrutura de pastas e frontmatter.

Se você quiser uma ordem específica:

---
title: "Quick Start"
order: 1
---

Se você não especificar a ordem, o Docsbook classifica alfabeticamente. Mova arquivos para pastas ordenadas se precisar de agrupamento explícito.

Você pode excluir sidebars.js, docusaurus.config.js, babel.config.js e o diretório src/ após a migração.

Passo 3: Conectar Docsbook#

Seus documentos já estão em docs/. Conecte o repositório:

  • docsbook.io → Faça login com o GitHub
  • Cole github.com/yourorg/yourrepo
  • Site ao vivo em docsbook.io/yourorg/yourrepo

Passo 4: Domínio personalizado#

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

  • Dashboard do Docsbook → Configurações → Domínio
  • Insira docs.yourcompany.com
  • Atualize DNS: CNAME docs → cname.vercel-dns.com
  • Espere 5 minutos para SSL

Passo 5: preservação de URL#

Os URLs do Docusaurus geralmente se parecem com:

docs.yourcompany.com/docs/intro
docs.yourcompany.com/docs/category/guides/getting-started

Os URLs do Docsbook correspondem aos seus caminhos de arquivo:

docs.yourcompany.com/intro.md → docs.yourcompany.com/intro
docs.yourcompany.com/guides/getting-started.md → docs.yourcompany.com/guides/getting-started

Se o seu Docusaurus tinha um prefixo /docs/ e você deseja manter a paridade:

Opção A: renomeie a pasta local docs/ para manter o prefixo nos URLs (o Docsbook servirá de um caminho diferente).

Opção B: adicione redirecionamentos de URLs antigas /docs/* para novas URLs /* no seu CDN ou camada DNS.

Passo 6: Descartar o CI/CD#

Uma vez que o Docsbook está servindo tráfego:

# Files you can delete
rm -rf .docusaurus/
rm -rf build/
rm -rf node_modules/
rm docusaurus.config.js
rm sidebars.js
rm babel.config.js
rm -rf src/
rm -rf static/
# Keep docs/ — it is your source

Arquivo de fluxo de trabalho do GitHub Actions para implantação do Docusaurus: também excluir.

O resultado: docs implantados em cada git push para main, nenhum minuto de CI utilizado.

O que você ganha#

Docusaurus Docsbook
Tempo de construção 30–120 segundos por push 5 segundos de configuração total
Custo de hospedagem Vercel/Netlify nível pro Incluído
Chat de IA Trabalho de plugin Integrado
Traduções Configuração por local + pipeline de tradução Integrado, 15 idiomas
Migrações de versão principal A cada 18 meses Nunca
Manutenção de tema Desvio de Swizzle Tokens de cor, sem manutenção

O que você abre mão#

  • Incorporações de componentes React dentro da documentação (hospede-os em outro lugar, link para dentro)
  • Controle total do tema swizzle (você recebe tokens de cor/fonte/layout)
  • Ecossistema de plugins (na maioria dos casos, já estão integrados)

Casos extremos#

Algolia DocSearch#

Você pode continuar usando o Algolia DocSearch no Docsbook (apontando para seu novo domínio). Ou use a busca integrada do Docsbook, que está incluída gratuitamente.

Página de destino personalizada#

Docusaurus geralmente tem uma página de destino personalizada em / construída em React. O Docsbook serve seu README.md em /. Se você quiser uma página de destino no estilo marketing, hospede-a separadamente e aponte o Docsbook para docs.yourcompany.com em vez de yourcompany.com.

Versionamento#

O padrão docs/versioned_docs/version-1.0/ do Docusaurus não é suportado diretamente. Opções:

  • Use espaços de trabalho Docsbook separados por versão (docsbook.io/yourorg/yourrepo-v1)
  • Use branches do Git e altere a branch indexada
  • Descontinue versões antigas (a maioria das equipes descobre que as mantinha por hábito)

Cronograma#

  • Projeto OSS, ~80 páginas, MDX mínimo: 2 horas
  • Startup, ~300 páginas, MDX moderado: meio dia
  • Estágio intermediário, ~1000 páginas, MDX pesado: 1–2 dias

Teste a migração antes de se comprometer com ela. Publicar um segundo site do mesmo repositório não custa nada e não muda nada sobre o deploy do Docusaurus que ainda atende seus leitores — se o resultado não alcançar paridade, você perdeu os cinco segundos que levou.

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

Próximos passos#

Updated

Esta página foi útil?

Desenvolvido por Docsbook