Configurando MDBook com Mermaid e JotDown

Este documento explica como configurar o MDBook com o plugin Mermaid para criar diagramas elegantes e funcionais em nossa documentação, e como integramos o JotDown para um fluxo de trabalho perfeito entre o Notion e nossa documentação. Nossa configuração utiliza versões específicas e testadas que garantem compatibilidade e estabilidade.

Versões Compatíveis e Testadas

Estamos utilizando a seguinte combinação de versões que comprovadamente funcionam bem juntas:

  • mdbook: v0.4.40
  • mdbook-mermaid: 0.15.0
  • mermaid.js: 8.11.0
  • JotDown: versão mais recente

⚠️ IMPORTANTE: A compatibilidade entre estas versões é fundamental para o funcionamento correto dos diagramas. Recomendamos fortemente usar exatamente estas versões.

Pré-requisitos

  • Rust instalado (para usar Cargo)
  • Permissões para instalar pacotes via Cargo

Instalação das Ferramentas

1. Instale o MDBook versão 0.4.40

cargo install mdbook --version 0.4.40

2. Instale o preprocessador mdbook-mermaid versão 0.15.0

cargo install mdbook-mermaid --version 0.15.0

3. Verifique a instalação e versões

mdbook --version
# Deve mostrar: mdbook v0.4.40

mdbook-mermaid --version
# Deve mostrar: mdbook-mermaid 0.15.0

Estrutura de Diretórios

Organizamos nossa documentação em diretórios específicos para manter o projeto limpo e estruturado:

docs/
├── book.toml                  # Arquivo de configuração principal
├── SUMMARY.md                 # Índice da documentação
├── *.md                       # Arquivos de conteúdo
├── mermaid-config/            # Arquivos relacionados ao Mermaid
│   ├── mermaid.min.js         # Biblioteca Mermaid (v8.11.0)
│   └── mermaid-init.js        # Script de inicialização
└── css-docs/                  # Arquivos de estilo
    └── custom.css             # CSS personalizado

Configuração do Mermaid

1. Baixe a versão 8.11.0 do Mermaid.js

# Criando diretório organizado para arquivos de configuração Mermaid
mkdir -p docs/mermaid-config

# Baixando a versão específica do Mermaid que é compatível
curl -o docs/mermaid-config/mermaid.min.js https://cdn.jsdelivr.net/npm/mermaid@8.11.0/dist/mermaid.min.js

2. Crie o arquivo de inicialização

echo 'window.mermaid.initialize({startOnLoad: true});' > docs/mermaid-config/mermaid-init.js

3. Configure o book.toml

Seu arquivo book.toml deve incluir as seguintes configurações:

[book]
title = "NotionAiAssistant: A Jornada do Desenvolvimento"
authors = ["Equipe NotionAiAssistant"]
description = "Documentação da jornada de desenvolvimento do NotionAiAssistant"
src = "."
language = "pt"

[preprocessor.mermaid]
command = "mdbook-mermaid"

[output.html]
default-theme = "rust"
preferred-dark-theme = "navy"
additional-css = ["./css-docs/custom.css"]
additional-js = ["./mermaid-config/mermaid.min.js", "./mermaid-config/mermaid-init.js"]

Integração com JotDown

Para otimizar nosso fluxo de trabalho entre o Notion e nossa documentação MDBook, integramos o JotDown, que proporcionou vários benefícios importantes:

Configurando o JotDown

  1. Clone e compile o repositório JotDown:
git clone https://github.com/Harry-027/JotDown
cd JotDown
cargo build --release
  1. Configure o token da API do Notion em seu ambiente:
export NOTION_TOKEN="seu_token_de_integracao_notion"
  1. Configure seu cliente MCP (como o Claude desktop) para usar o JotDown para geração automatizada de documentação.

Benefícios do JotDown em Nosso Fluxo de Trabalho

  • Sincronização de Conteúdo: Extrai automaticamente conteúdo do Notion para nossa estrutura MDBook
  • Consistência: Mantém formatação consistente entre o Notion e o MDBook
  • Automação: Reduz tarefas manuais na conversão de páginas do Notion para capítulos do MDBook
  • Eficiência: Acelera significativamente o processo de documentação

Como Criar Diagramas Mermaid Funcionais

Para garantir a compatibilidade com nossa configuração (mdbook v0.4.40, mdbook-mermaid 0.15.0 e mermaid.js 8.11.0), siga estas diretrizes:

1. Sintaxe Correta para Diagramas

Com a versão 8.11.0 do Mermaid, você deve usar a sintaxe graph (e não flowchart):

```mermaid
graph TD
    A[docs/] --> B[book.toml]
    A --> C[SUMMARY.md]
    A --> D[Arquivos .md]
    A --> E[mermaid-config/]
    A --> F[css-docs/]
    E --> G[mermaid.min.js]
    E --> H[mermaid-init.js]
    F --> I[custom.css]


Observe que usamos `graph TD` (top-down) para fluxogramas verticais.

### 2. Exemplo Funcional de Fluxograma

Aqui está um exemplo que funciona perfeitamente com nossa versão:

```markdown
```mermaid
graph TD
    A[Início] --> B{Decisão}
    B -->|Sim| C[Resultado 1]
    B -->|Não| D[Resultado 2]


### 3. Tipos de Diagramas Disponíveis

Com a versão 8.11.0, você pode criar:
- Fluxogramas (`graph`)
- Diagramas de sequência (`sequenceDiagram`)
- Diagramas de classe (`classDiagram`)
- Diagramas de estado (`stateDiagram`)
- Diagramas ER (`erDiagram`)
- Gráficos de Gantt (`gantt`)
- Gráficos de pizza (`pie`)

## Por Que Estas Versões São Importantes

A combinação específica de mdbook v0.4.40, mdbook-mermaid 0.15.0 e mermaid.js 8.11.0 foi cuidadosamente testada e validada em nosso ambiente. Esta configuração oferece:

1. **Estabilidade**: Evita problemas de compatibilidade entre componentes
2. **Consistência**: Garante que todos os diagramas sejam renderizados da mesma forma
3. **Confiabilidade**: Previne erros de renderização e falhas inesperadas
4. **Manutenção simplificada**: Facilita o suporte e resolução de problemas

## Solução de Problemas Comuns

### Erro de Sintaxe no Gráfico

Se você vir "Syntax error in graph":

1. Verifique se está usando `graph` (e não `flowchart`) com a versão 8.11.0
2. Confirme que a estrutura do diagrama está correta
3. Teste seu diagrama no [Mermaid Live Editor](https://mermaid.live/) configurado para versão 8.11.0

### Diagramas Não Aparecem

Se os diagramas não aparecerem:

1. Abra o console do navegador (F12) e procure por erros
2. Verifique se os caminhos no `book.toml` estão corretos
3. Confirme se o arquivo mermaid.min.js tem aproximadamente 900 KB (tamanho correto para v8.11.0)

## Conclusão

Seguindo esta configuração com as versões especificadas (mdbook v0.4.40, mdbook-mermaid 0.15.0, mermaid.js 8.11.0 e JotDown), você garantirá que seus diagramas Mermaid sejam renderizados corretamente na documentação, e que seu fluxo de trabalho entre Notion e MDBook seja eficiente. A estrutura organizada de diretórios e a padronização da sintaxe facilitam a manutenção e expansão futura da documentação.