Skip to main content

docusaurus

![Docusaurus logo](../../apps/docusaurus/static/img/logo.svg)

Sumário​

Setup​

https://docusaurus.io/docs/installation

pnpm dlx create-docusaurus@latest apps/docusaurus classic --typescript

cd apps/docusaurus/
pnpm start

pnpm build  # contents will be generated within the /build directory

Configuration​

  • apps/docusaurus/docusaurus.config.ts
cd ~/dev/nextjs/qb-monorepo/apps/docusaurus/docs
ln -s ../../../docs/ docs

ls -la
docs -> ../../../docs/

⛔ Não usar symlinks!​

The error "Cannot read properties of undefined (reading 'id')" in Docusaurus, particularly when using symlinks, often indicates that Docusaurus is unable to correctly resolve the content or metadata of a linked document. This typically occurs when:

  • Docusaurus does not fully support symlinks in the way they are being used. While Docusaurus can handle some symlinks, particularly for individual files, symlinking entire directories into the docs directory can lead to issues with its internal content resolution mechanisms. It might not correctly traverse the symlinked directory or extract the necessary metadata (like id) from the linked files.
  • Incorrect symlink creation or path resolution. If the symlink is not created correctly, or if the paths within the symlinked content are relative and become invalid when accessed through the symlink, Docusaurus might fail to find the expected id property.

To address this issue:

  • Avoid symlinking entire directories into docs if possible. Instead, consider alternative approaches like:
    • Monorepo setup: If you are managing multiple related projects, consider a monorepo structure where Docusaurus can directly access the source files without needing symlinks.
  • O Docusaurus (especialmente em versões mais recentes) tem limitações com symlinks, principalmente quando eles apontam para diretórios inteiros fora do projeto. Isso pode quebrar a resolução de metadados (como o id dos documentos), porque o Docusaurus não consegue "traversar" corretamente o link simbólico para extrair informações como frontmatter ou estrutura de pastas.
  • No seu caso, o symlink docs -> ../../../docs/ faz com que o Docusaurus tente processar arquivos fora do escopo esperado, levando ao erro de propriedade indefinida.

A ideia é fazer o Docusaurus "ver" diretamente a pasta docs da raiz do monorepo como se fosse parte do seu projeto docusaurus. Isso evita symlinks e garante que o Docusaurus possa resolver metadados corretamente. Em um monorepo (como o seu qb-monorepo), você pode compartilhar pastas entre projetos usando configurações do Docusaurus, sem copiar arquivos ou criar links.

Passos conceituais para implementar (sem alterar nada agora):​

  1. Configure o plugin content-docs no docusaurus.config.ts:
    • No arquivo docusaurus.config.ts, você pode definir o path do plugin de docs para apontar para a pasta raiz.
    • Exemplo conceitual (não execute ainda): 
      // Em docusaurus.config.ts, dentro da seção 'docs' do preset 'classic':
      docs: {
        path: '../../docs',  // Aponta diretamente para a pasta docs/ na raiz do monorepo
        sidebarPath: './sidebars.ts',  // Mantém o sidebar como está
        // Outras opções...
      },
      • Isso faz com que o Docusaurus use a pasta ../../docs/ como a "raiz" dos documentos, em vez de uma pasta local. O sidebarPath pode ser ajustado para gerar a sidebar baseada nessa pasta externa.
    • Por que funciona? O Docusaurus roda em Node.js e pode resolver caminhos relativos fora do projeto, desde que o caminho seja válido. Isso evita symlinks porque o plugin acessa os arquivos diretamente via filesystem.

Possíveis desafios:​

  • Caminhos relativos: Se o monorepo for movido ou executado em ambientes diferentes (ex.: CI/CD), caminhos como ../../../docs podem quebrar. Considere usar caminhos absolutos ou variáveis de ambiente.
  • Dependências: Certifique-se de que o Docusaurus tenha acesso à pasta (permissões de leitura).
  • Plugins externos: Se você usar plugins para conteúdo externo, explore opções como @docusaurus/plugin-content-docs com path customizado ou integrações com Git (para repos externos).

index.md front matter​

---
sidebar_position: 0
---

_category_.json file​

docs/docusaurus/docs/tutorial-basics/_category_.json

{
  "label": "Tutorial - Basics",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "5 minutes to learn the most important Docusaurus concepts."
  }
}

MDX files​