Skip to main content

Arquitetura de Plugins de Documentação

O workspace de documentação tupynambalucas.dev é alimentado estritamente pelo Docusaurus v3 e utiliza uma combinação de padrões padrão do React e transformadores avançados de Árvore de Sintaxe Abstrata (AST).

1. Wrappers de Plugins de Domínio (Arquitetura SSOT)​

Para aplicar o Single Source of Truth (SSOT) e manter um docusaurus.config.ts limpo, o monorepo utiliza um Preset Customizado do Docusaurus (@/docs/preset/). Este preset é o núcleo autoritativo que encapsula e configura todos os motores de documentação subjacentes.

Em vez de declarar os plugins principais do Docusaurus diretamente no array de presets, utilizamos Wrappers de Plugins de Domínio (localizados em preset/plugins/):

  • content-docs
  • content-blog
  • content-pages

O Ciclo de Vida do Wrapper​

Cada wrapper de domínio importa o plugin nativo do Docusaurus (por exemplo, @docusaurus/plugin-content-docs), mescla dinamicamente nossas regras corporativas e, em seguida, invoca o plugin nativo. Isso garante que todas as instâncias de documentação — seja o manual principal, o roadmap ou as especificações de workspaces — sejam forçadas a passar automaticamente pelos nossos pipelines de sanitização e injeção de AST.

  1. Validação de Opções: Os wrappers reexportam validateOptions para atender aos validadores de esquema estritos do Docusaurus.
  2. Injeção de AST: Os wrappers anexam automaticamente o plugin customizado remark-project-variables ao array remarkPlugins.
  3. Preservação de Contexto: Os wrappers retornam exatamente o nome original (por exemplo, docusaurus-plugin-content-docs) para garantir que os componentes de UI do React resolvam corretamente os dados de contexto global durante a Geração do Lado do Servidor (SSG).

2. O Plugin remark-project-variables​

Para manter um monorepo genérico e pronto para copiar e colar, a documentação NÃO DEVE conter nomes de marcas ou URLs hardcoded (por exemplo, example.com). Em vez disso, os autores devem escrever tokens genéricos usando wrappers de porcentagem, como tupynambalucas.dev ou Tupynambalucas.

Como Funciona​

  1. Transformação de AST: O plugin customizado remark-project-variables se conecta ao pipeline de compilação MDX do unified/remark.
  2. Intercepção de Nó de Texto: Ele percorre a AST do Markdown (mdast) utilizando unist-util-visit.
  3. Resolução de Valores: Ele intercepta nós do tipo text, inlineCode, link e image, e busca por padrões como tupynambalucas.dev.
  4. Substituição: Ele substitui esses tokens por valores reais obtidos de uma única fonte de verdade (project.config.json) antes que o MDX seja compilado em React JSX.

Esta arquitetura garante que os embeddings de IA RAG (como os vetores de cortex/memory) ingeriram os arquivos de origem agnósticos, evitando a alucinação de marcas quando o repositório for bifurcado ou aplicado a novos clientes.

3. Coleções Dinâmicas e Localização (L10n)​

Para dar suporte a múltiplas instâncias de conteúdo e à localização contínua orientada por GitOps, o monorepo implementa um Plugin Locales Sync dinâmico (preset/plugins/locales-sync/).

O Ciclo de Vida Dinâmico​

Em vez de fazer o check-in manual dos templates de UI traduzidos do Docusaurus e chumbados nos caminhos absolutos, o docusaurus.config.ts utiliza uma propriedade personalizada chamada collection no formato [namespace]/[content] (ex: portal/docs):

  1. Orquestração pelo Preset: O Preset Personalizado intercepta as configurações de docs e blog, calcula dinamicamente o path absoluto para os arquivos markdown (collections/namespaces/[namespace]/content/[content]) e o injeta diretamente no motor.
  2. Extração de Traduções: O comando nativo do Docusaurus write-translations extrai os arquivos JSON no formato Chrome i18n (como code.json, theme/navbar.json) e os armazena de forma segura em collections/namespaces/[namespace]/content/messages/.
  3. Descompactação no Build: Durante o pipeline kb:docusaurus:portal:build, o plugin plugin-locales-sync lê dinamicamente as pastas locales/[locale]/ sincronizadas e as mapeia de volta para o formato nativo da engine Docusaurus dentro de i18n/[locale]/docusaurus-plugin-content-[type]-[id]/.

Este plugin garante a separação completa entre o conteúdo traduzido e a engine executável do Docusaurus, operando inteiramente sob convenções de diretório GitOps sem mapeamentos hardcoded.