Plataformas de documentação self-hosted

Por que as equipes fazem self-hosting da sua documentação

As plataformas de documentação self-hosted são ferramentas open source que você instala e roda na sua própria infraestrutura. O apelo é real e merece ser levado a sério. O controle de dados vem primeiro: seu conteúdo e os dados dos seus leitores ficam em servidores que você possui, algo que importa quando a documentação contém conhecimento interno sensível. O custo é o motivo seguinte — o software em si é gratuito, sem assinatura por assento. E a conformidade regulatória pode forçar a decisão por completo, quando uma regulamentação ou uma política de segurança exige que o conteúdo nunca saia do seu próprio ambiente.

Para equipes lideradas por engenharia que já operam infraestrutura, o self-hosting pode ser uma opção genuinamente boa. Se você roda Kubernetes, tem um pipeline de CI/CD e trata a documentação como código junto da sua aplicação, adicionar um gerador de sites estáticos ou uma wiki self-hosted é um passo marginal pequeno. Este guia cobre cinco das opções open source mais sólidas, com prós e contras honestos, e termina com o argumento a favor de quando uma plataforma gerenciada é realmente a melhor decisão.

Quanto custa de verdade o self-hosting

A licença é gratuita. A plataforma não. Antes de se comprometer, considere as partes que nunca aparecem em uma página de preços:

• Configuração. Alguém precisa provisionar servidores ou contêineres, configurar a build, conectar um domínio e implantar a primeira versão. Isso é tempo de desenvolvimento, não um fim de semana para a maioria das equipes.
• Atualizações. Os projetos open source publicam mudanças que quebram compatibilidade. Cada versão maior é uma migração que pertence a você, e pular atualizações significa rodar software sem patches.
• Busca. Uma boa busca de documentação não é gratuita. Os geradores estáticos costumam precisar de um serviço de busca de terceiros ou de um motor de busca self-hosted que você também precisa rodar e indexar.
• Backups. O conteúdo, os arquivos enviados e o estado do banco de dados precisam de uma estratégia de backup que você teste, não apenas configure.
• Autenticação. Restringir quem pode ler ou editar implica integrar um provedor de identidade, gerenciar sessões e manter essa camada com patches.

Nada disso é motivo para evitar o self-hosting. É motivo para entrar de olhos abertos, porque o custo recorrente do self-hosting é medido em horas de engenharia, não em dólares.

1. Docusaurus

Stack: gerador de sites estáticos em React, MDX e Node.js (open source, da Meta).

Modelo de edição: docs-as-code. Os redatores editam arquivos Markdown/MDX em um repositório git; o site é construído a partir do código a cada commit.

Necessidades de hospedagem: gera HTML estático que você pode hospedar em qualquer lugar — uma hospedagem estática, armazenamento de objetos ou seu próprio servidor web. Você é dono do pipeline de build e do deploy.

Para quem é: equipes de desenvolvimento que publicam documentação de produto e de API, que querem controle total sobre o design e se sentem confortáveis com React e git. O Docusaurus é polido, consciente do versionamento e tem um forte ecossistema de plugins. A contrapartida é que não há editor integrado para redatores não técnicos, e a hospedagem, a busca e o analytics dependem de plugins e serviços de terceiros que você mesmo monta.

2. MkDocs com Material

Stack: gerador de sites estáticos em Python, Markdown puro, com o tema Material for MkDocs.

Modelo de edição: docs-as-code. O conteúdo são arquivos Markdown em um repositório; o MkDocs os constrói em um site estático. Não exige MDX nem React, o que mantém simples a superfície de autoria.

Necessidades de hospedagem: produz HTML estático para qualquer hospedagem estática ou seu próprio servidor. A busca do lado do cliente vem no tema, o que elimina uma dor de cabeça de infraestrutura comum.

Para quem é: equipes lideradas por engenharia que querem documentação limpa, rápida e centrada em Markdown sem a curva de aprendizado do React. O Material for MkDocs é lindo de fábrica e muito querido para documentação técnica. Aplica-se a mesma contrapartida fundamental do Docusaurus: é propriedade dos desenvolvedores, os redatores não técnicos precisam trabalhar em Markdown e git, e as traduções, o controle de acesso e o analytics ficam por sua conta adicionar.

3. BookStack

Stack: aplicação em PHP (Laravel) respaldada por um banco de dados. Servidor self-hosted, não um gerador estático.

Modelo de edição: edição WYSIWYG e Markdown no navegador. O conteúdo é organizado em uma hierarquia simples e intuitiva de prateleira / livro / capítulo / página.

Necessidades de hospedagem: um servidor PHP em execução mais um banco de dados (MySQL/MariaDB). Você mantém a aplicação, o banco de dados, os backups e as atualizações.

Para quem é: equipes que querem uma wiki interna ou base de conhecimento self-hosted com um editor amigável que as pessoas não técnicas realmente consigam usar, sem um fluxo de git. O BookStack é refrescantemente simples. É menos adequado para documentação pública polida e com marca, com o controle de SEO e design que um site de produto espera, e como qualquer aplicação respaldada por banco de dados, precisa de cuidado operacional real.

4. Wiki.js

Stack: aplicação em Node.js com banco de dados de apoio. Servidor self-hosted.

Modelo de edição: edição no navegador com vários editores à escolha (Markdown, WYSIWYG e mais), além de um modo opcional de armazenamento respaldado por git para que o conteúdo possa ser espelhado em um repositório.

Necessidades de hospedagem: um servidor Node.js em execução e um banco de dados (PostgreSQL é comum). Você é dono das atualizações, dos backups e da configuração de autenticação.

Para quem é: equipes que querem uma wiki self-hosted moderna e flexível com opções de autenticação integradas e a tranquilidade do armazenamento respaldado por git. O Wiki.js é rico em recursos e configurável. Essa flexibilidade também é o seu custo: há mais a configurar e manter, e colocar em pé uma instância de nível produção, protegida e com backup, é um projeto real mais do que uma instalação rápida.

5. Outline

Stack: wiki de equipe open source moderna, construída em Node.js com banco de dados de apoio. Self-hosted (o projeto também oferece uma opção em nuvem gerenciada).

Modelo de edição: editor de texto avançado rápido e por blocos no navegador, projetado para conhecimento interno colaborativo mais do que para edição de arquivos estáticos.

Necessidades de hospedagem: um serviço Node.js em execução, um banco de dados e serviços de apoio para o deploy self-hosted. Como em qualquer wiki de servidor de aplicação, você é dono da operação de ponta a ponta.

Para quem é: equipes que querem uma experiência de wiki interna elegante, no estilo Notion, que possam hospedar por conta própria. O Outline é uma wiki de equipe open source genuinamente moderna com uma experiência de escrita limpa. É voltado ao conhecimento interno da equipe, então se o seu objetivo é documentação de produto pública, com marca e otimizada para SEO, você o estaria empurrando para além da sua intenção de design principal, e ainda carrega toda a carga operacional do self-hosting.

Os custos ocultos do self-hosting de documentação

O padrão em todas as opções acima é o mesmo: a ferramenta é gratuita e a operação não. Vale a pena nomear os custos que as equipes subestimam de forma consistente.

O tempo de desenvolvimento é o preço real. Cada hora que um engenheiro passa provisionando servidores, depurando uma build ou migrando entre versões maiores é uma hora que não dedica ao seu produto. Para uma equipe pequena, esse custo de oportunidade costuma ofuscar o preço de uma assinatura gerenciada.

Os plugins são uma superfície de manutenção. Os geradores estáticos se apoiam em plugins para busca, sitemaps, redirecionamentos e analytics. Cada plugin é uma dependência que pode quebrar na próxima atualização, e o trabalho de integrá-los em um site coerente é contínuo, não pontual.

A infraestrutura de busca é um projeto em si. Os leitores esperam uma busca rápida e relevante. Entregá-la em self-hosting significa rodar um motor de busca ou conectar um serviço de busca hospedado e manter o índice atualizado — mais peças móveis para administrar.

O SSL e os domínios precisam de cuidado. Os certificados vencem, as renovações falham em silêncio e um certificado vencido deixa sua documentação fora do ar. Os domínios personalizados, os redirecionamentos e o HTTPS são todos de sua responsabilidade configurar e monitorar.

As traduções são manuais. Nenhuma das ferramentas self-hosted traduz seu conteúdo por você. Atender a um público multilíngue significa um fluxo de localização à parte, tradução externa e o trabalho de manter cada idioma sincronizado com o original conforme ele muda.

Quando uma plataforma gerenciada faz mais sentido

Sejamos diretos: o OpenDocs não é self-hosted nem open source. É uma plataforma de documentação SaaS gerenciada. Se uma regra de conformidade exige que o conteúdo nunca saia dos seus próprios servidores, uma ferramenta self-hosted da lista acima é a resposta certa, e você deveria parar de ler aqui. Mas para a maioria das equipes o objetivo real não é rodar servidores — é ser dona do próprio conteúdo e publicar uma boa documentação sem uma carga operacional. Esse é o caso para o qual o OpenDocs foi construído.

Hospedagem gerenciada e um domínio personalizado real. Publique um portal de documentação com a sua marca no seu próprio domínio, com temas personalizados, SEO integrado (metatags, sitemap, URLs canônicas), busca para leitores e comentários de página — sem provisionar um único servidor, renovar um certificado nem cuidar de uma build.

Um editor visual que os redatores não técnicos conseguem usar. O OpenDocs tem um editor por blocos, então seus redatores não precisam de conhecimento de Markdown nem de git para contribuir. Isso resolve justamente a lacuna que os geradores estáticos propriedade dos desenvolvedores deixam aberta.

Portabilidade de dados sem rodar servidores — esta é a chave. O medo habitual com SaaS é o lock-in. O OpenDocs responde a isso com GitHub Sync bidirecional em todos os planos: quando uma página é salva, o OpenDocs confirma Markdown com frontmatter YAML (título, slug, ordem, pai) no seu próprio repositório do GitHub, e os pushes para esse repositório voltam às suas páginas por webhook, com detecção de conflitos e comparação lado a lado. Na prática, isso lhe dá uma exportação contínua e versionada em Markdown de toda a sua documentação, vivendo em um repositório git que você controla. Seu conteúdo nunca fica preso — é a história de docs-as-code sem que você precise hospedar a documentação. Os redatores usam o editor visual; os engenheiros usam git; ambos permanecem sincronizados.

Traduções com IA que se mantêm sincronizadas. O OpenDocs inclui Traduções com IA para 38 idiomas que se mantêm sincronizadas com as atualizações do original. As traduções usam sua própria chave de API da Anthropic (BYOK), então o consumo é cobrado diretamente na sua conta da Anthropic. Este é o fluxo multilíngue que o self-hosting obriga você a construir na mão.

Um servidor MCP para que sua documentação alimente agentes de IA. Cada espaço publicado é consultável por meio do servidor MCP (Model Context Protocol) integrado do OpenDocs, protegido com uma chave de API do OpenDocs. Clientes compatíveis com MCP como o Claude Desktop e o Claude Code podem chamar ferramentas como search_pages e get_page para ler sua documentação ao vivo diretamente — sem scraping, sem exportações desatualizadas. Sua documentação publicada funciona ao mesmo tempo como fonte de conhecimento ao vivo para agentes de IA.

Preços fixos e previsíveis. Comece com uma avaliação gratuita de 14 dias (sem cartão de crédito, todos os recursos do Pro; a publicação em domínio personalizado é ativada ao fazer upgrade). O Pro custa $55/mês ($45.65/mês cobrado anualmente, $547.80/ano) com 5 membros incluídos, e membros extras a $5/membro/mês no mensal ou $4 no anual. O Enterprise custa $99/mês ($82.50/mês cobrado anualmente, $990/ano) com 10 membros incluídos, e adiciona analytics, exportação para PDF e Markdown, acesso à API com documentação completa da API, sem selo "Powered by", SSO/SAML, registros de auditoria e suporte prioritário. Os leitores de documentação pública nunca contam como assentos cobrados.

Perguntas frequentes

Existe uma alternativa open source ao GitBook?

Sim, várias. Docusaurus e MkDocs Material são geradores de sites estáticos open source que constroem a documentação a partir de Markdown em um repositório git. BookStack e Wiki.js são plataformas wiki open source self-hosted com editor no navegador. Outline é uma wiki de equipe open source moderna. Todas são gratuitas para rodar nos seus próprios servidores, mas você é responsável pela hospedagem, pelas atualizações, pela busca, pelos backups e pela autenticação.

O self-hosting de documentação é mais barato que uma plataforma gerenciada?

O software é gratuito, mas o self-hosting raramente é. Você paga em custos de servidor e, mais importante ainda, em tempo de engenharia: configuração inicial, atualizações de versão, infraestrutura de busca, certificados SSL e domínios, backups e patches de segurança. Para uma equipe pequena, o custo recorrente de um desenvolvedor mantendo o stack costuma superar o de uma assinatura gerenciada de preço fixo. O self-hosting vence em custo principalmente quando você já opera infraestrutura e tem capacidade operacional de sobra.

Como mantenho a propriedade do meu conteúdo em uma plataforma SaaS?

Escolha uma plataforma com portabilidade de dados real. O OpenDocs oferece GitHub Sync bidirecional: cada salvamento de página confirma Markdown com frontmatter YAML de volta ao seu próprio repositório do GitHub. Isso lhe dá uma exportação contínua e versionada em Markdown de toda a sua documentação, vivendo em um repositório que você controla, então você nunca fica preso mesmo sem rodar servidor algum.

A documentação self-hosted pode alimentar agentes de IA?

Somente se você construir a integração por conta própria. As ferramentas self-hosted produzem HTML e Markdown, então um agente de IA teria que fazer scraping das páginas ou consumir arquivos exportados que ficam desatualizados. O OpenDocs expõe cada espaço publicado por meio de um servidor MCP (Model Context Protocol) integrado e protegido com uma chave de API, para que clientes compatíveis com MCP como o Claude Desktop e o Claude Code consultem sua documentação ao vivo diretamente, sem scraping e sem exportações desatualizadas.

Qual é a melhor plataforma de documentação self-hosted?

Depende de quem escreve sua documentação. Para docs de produto e API a cargo de desenvolvedores, Docusaurus e MkDocs Material são excelentes porque o conteúdo vive como Markdown no git. Para uma base de conhecimento de equipe onde pessoas não técnicas editam no navegador, BookStack, Wiki.js ou Outline se encaixam melhor. Todas pressupõem que você tem a capacidade de engenharia para implantar e manter o stack por conta própria.

Comparações e guias relacionados

• OpenDocs vs Docusaurus — publicação gerenciada frente a um gerador de sites estáticos self-hosted.
• Docs as code — como o GitHub Sync lhe dá um fluxo de git sem você mesmo rodar a documentação.
• Melhor software de documentação — um panorama mais amplo de ferramentas de documentação.
• Melhores alternativas ao GitBook — opções hospedadas e self-hosted comparadas.
• Melhor software de base de conhecimento — ferramentas para bases de conhecimento internas e voltadas ao cliente.
• Documentação MCP — como tornar sua documentação consultável por agentes de IA.