Skip to main content

Documentation Plugins Architecture

The tupynambalucas.dev documentation workspace is strictly powered by Docusaurus v3 and uses a combination of standard React patterns and advanced Abstract Syntax Tree (AST) transformers.

1. Domain Plugin Wrappers (SSOT Architecture)​

To enforce the Single Source of Truth (SSOT) and maintain a clean docusaurus.config.ts, the monorepo uses a Custom Docusaurus Preset (@tupynambalucas-dev/corporate-preset). This preset is the authoritative core that encapsulates and configures all underlying documentation engines.

Instead of declaring Docusaurus core plugins directly in the preset array, we use Domain Plugin Wrappers (located in corporate/packages/preset/src/plugins/):

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

The Wrapper Lifecycle​

Each domain wrapper imports the native Docusaurus plugin (e.g., @docusaurus/plugin-content-docs), dynamically merges our enterprise rules, and then invokes the native plugin. This guarantees that every documentation instance—whether it is the primary handbook, the roadmap, or the workspaces specs—is forced to run through our sanitization and AST injection pipelines automatically.

  1. Option Validation: The wrappers re-export validateOptions to satisfy Docusaurus's strict schema validators.
  2. AST Injection: The wrappers automatically append the custom remark-project-variables plugin to the remarkPlugins array.
  3. Context Preservation: The wrappers return the exact original name (e.g., docusaurus-plugin-content-docs) to ensure the React UI components correctly resolve the global context data during Server-Side Generation (SSG).

2. The remark-project-variables Plugin​

To maintain a copy-pasteable, generic monorepo, the documentation MUST NOT contain hardcoded brand names or URLs (e.g., example.com). Instead, authors must write generic tokens using percentage wrappers, such as tupynambalucas.dev or Tupynambalucas.

How it Works​

  1. AST Transformation: The custom remark-project-variables plugin hooks into the unified/remark MDX compilation pipeline.
  2. Text Node Interception: It traverses the Markdown AST (mdast) using unist-util-visit.
  3. Value Resolution: It intercepts nodes of type text, inlineCode, link, and image, and searches for patterns like tupynambalucas.dev.
  4. Replacement: It replaces those tokens with actual values pulled from a single source of truth (project.config.json) before the MDX is compiled into React JSX.

This architecture ensures that AI RAG embeddings (like the cortex/memory vectors) ingest the agnostic source files, avoiding brand hallucination when the repository is forked or applied to new clients.

3. Dynamic Collections and Localization (L10n)​

To support multiple content instances and seamless GitOps-driven localization, the monorepo implements a dynamic Locales Sync Plugin (corporate/packages/preset/src/plugins/locales-sync/).

The Dynamic Lifecycle​

Instead of manually checking in translated Docusaurus UI templates and hardcoding paths, the docusaurus.config.ts uses a custom collection property in the format [namespace]/[content] (e.g., portal/docs):

  1. Preset Orchestration: The Custom Preset intercepts the docs and blog configurations, calculates the absolute path for the markdown files (collections/namespaces/[namespace]/content/[content]), and injects it dynamically into the engine.
  2. Translation Extraction: Native Docusaurus write-translations dumps Chrome i18n JSON files (like code.json, theme/navbar.json) which are stored securely in collections/namespaces/[namespace]/content/messages/.
  3. Build-Time Unpacking: During the pnpm portal:build pipeline, the plugin-locales-sync dynamically reads the synchronized locales/[locale]/ folders and maps them back into the native Docusaurus engine format inside i18n/[locale]/docusaurus-plugin-content-[type]-[id]/.

This plugin ensures complete separation between translated content and the executable Docusaurus engine, operating entirely on GitOps folder conventions without hardcoded mappings.