Como renderizar diagramas de Mermaid com o tema do seu site: testamos Pele, do Obsidian ✅ yoDEV Tested

[Devy]

Para que seus diagramas de Mermaid sigam o tema de sua web, modo escuro incluído, renderize-os com Pele: uma biblioteca MIT do Obsidian que converte a mesma sintaxe de Mermaid em SVG cujas cores saem de variáveis CSS. Assim o diagrama muda junto com sua página em vez de manter a paleta de Mermaid. A instalamos, a colocamos ao lado de Mermaid.js em modo claro e escuro, e medimos as duas.

GitHub - obsidianmd/pele: Renders Mermaid diagrams faster than you'd run...

yoDEV Testado · 18 de outubro de 2026 Instalamos Pele 1.6.0 do npm e comparamos com Mermaid 12.2.0 no Node 22 e no Chromium headless, com o mesmo diagrama e o mesmo CSS. Os resultados que reportamos como nossos saem dessa prova.

O que é Pele e em que se diferencia de Mermaid.js?

Pele é uma biblioteca JavaScript que recebe texto em sintaxe Mermaid e devolve SVG. Não é um plugin de Mermaid nem depende de Mermaid: tem seu próprio parser, seu próprio mecanismo de layout e zero dependências em tempo de execução. Suporta todos os tipos de diagrama incluídos em Mermaid 12.1.0, desde diagramas de fluxo e de sequência até Gantt, C4, Sankey e mapas mentais.

Nasceu para Obsidian, o app de notas, com o objetivo de desenhar diagramas rápido e que coincidam com o tema do usuário. É mantido por Steph Ango (kepano) na organização obsidianmd do GitHub. O nome vem da deusa havaiana dos vulcões, não do jogador de futebol.

Você continua escrevendo Mermaid. O que muda é quem o desenha.

Por que os diagramas de Mermaid se veem mal em modo escuro?

Porque Mermaid tira suas cores de sua própria configuração de tema, não de sua folha de estilos. Em nossa prova colocamos o mesmo diagrama de fluxo na mesma página, com o mesmo CSS, e mudamos o navegador para modo escuro. Com seu tema padrão, Mermaid 12.2.0 manteve os nós brancos, e as linhas e pontas de seta continuaram em preto: sobre um fundo quase preto praticamente desaparecem. Mermaid sim traz temas próprios, mas se escolhem em sua configuração, e o CSS de sua página não chega até eles.

Em Pele, nós, linhas e rótulos leem suas cores de variáveis --pele-*. Cada valor hexadecimal do SVG que gerou era apenas um valor de fallback dentro de var(). Quando a página passou para escuro, o preenchimento dos nós mudou de rgb(242, 240, 229) para rgb(28, 27, 26) sem voltar a renderizar o diagrama: nosso contador de renders ficou em 1.

Como renderizar diagramas de Mermaid com o tema de sua web?

Você instala um pacote, sem dependências adicionais:

npm install pele

Depois passa o texto de Mermaid para render() e insere o SVG que devolve:

import { render } from 'pele';

const { svg } = render(`flowchart LR
  A[Mermaid text] --> B[SVG]`);

document.querySelector('#diagram').innerHTML = svg;

render() é síncrono e também funciona em Node sem DOM. Nós renderizamos o diagrama de prova do lado do servidor, onde Pele mede o texto com uma tabela de larguras incluída em vez de um canvas. Assim que funciona igual para converter Mermaid a SVG em um gerador de sites estáticos quanto no navegador.

Há outros dois pontos de entrada que convém conhecer:

• pele/lazy carrega cada tipo de diagrama a primeira vez que se usa: const { svg } = await renderAsync(source);
• pele/global define um objeto global pele para páginas sem bundler. Vem no pacote em dist/pele.global.js, e é a versão que carregamos no Chromium.

Como mudar as cores de um diagrama Mermaid com variáveis CSS?

Você define as variáveis em .pele ou em qualquer elemento que o contenha. A raiz <svg> de cada diagrama leva a classe .pele. O bloco seguinte é a paleta da documentação de temas de Pele, com uma variante escura sob prefers-color-scheme, e é exatamente o que usamos na prova:

.pele {
  --pele-bg: #fffcf0;
  --pele-fg: #100f0f;
  --pele-muted: #6f6e69;
  --pele-line: #100f0f;
  --pele-surface: #f2f0e5;
  --pele-surface-alt: #e6e4d9;
  --pele-border: #cecdc3;
  --pele-accent: #205ea6;
  --pele-critical: #af3029;
}
@media (prefers-color-scheme: dark) {
  .pele {
    --pele-bg: #100f0f;
    --pele-fg: #cecdc3;
    --pele-muted: #878580;
    --pele-line: #cecdc3;
    --pele-surface: #1c1b1a;
    --pele-surface-alt: #282726;
    --pele-border: #403e3c;
    --pele-accent: #4385be;
    --pele-critical: #d14d41;
  }
}

Na prática, você aponta essas variáveis aos tokens que seu site já tem. O conjunto completo de variáveis CSS que Pele oferece cobre:

• fundo, texto, texto secundário e linhas
• preenchimento de nós e de subgrafos, e bordas
• uma cor de acento, mais uma cor “crítica” para Gantt e kanban
• --pele-error, fontes, pesos de fonte e --pele-radius
• --pele-series-1 a --pele-series-8 para gráficos

Os elementos também levam classes como pele-node, pele-edge e pele-label, e você pode apontar a um nó concreto por seu id no código fonte com [data-id="…"].

Um detalhe com as fontes: Pele mede os rótulos para dimensionar as caixas, assim que precisa conhecer a fonte antes de desenhar. mount() a lê de --pele-font; com render() você a passa:

const fontFamily = getComputedStyle(container).fontFamily;
container.innerHTML = render(source, { fontFamily }).svg;

Quando usar render() e quando mount()?

Use render() quando você quer uma string: geradores de sites estáticos, renderização em servidor, pipelines de Markdown. Use mount() quando o diagrama vive em uma página que muda:

import { mount } from 'pele';

const diagram = mount(container, source);
diagram.update('flowchart LR\n  A[Draft] --> B[Published]');

mount() observa o contêiner e volta a distribuir o diagrama quando muda sua largura. Em nossa prova, ao reduzir o contêiner a 320 px, o diagrama da esquerda para a direita passou a ser vertical e o zoom se ativou sozinho. Reorganiza o diagrama em vez de encolhê-lo até que o texto fique ilegível.

mount() também maneja os erros no lugar. Quando lhe passamos para update() uma sintaxe quebrada, não lançou nenhuma exceção: o diagrama anterior ficou na tela, atenuado, com o erro do parser em sua borda inferior, e diagram.error.code devolveu syntax na linha 3. Com render(), os erros se lançam como PeleError, com code, line, column e um snippet que marca a coluna.

Pele é mais rápido e mais leve que Mermaid.js?

Segundo nossas medições, sim, embora a diferença de velocidade tenha sido menor que a cifra do título. A comparação do próprio projeto, que é autorreportada, indica:

• 230 kB em gzip frente a 1,6 MB
• tempos de render de 0,05–0,3 ms frente a 6–82 ms
• “até 500 vezes” mais rápido

Isso é o que medimos nós, em uma só máquina e com um diagrama de fluxo de cinco nós:

	Pele 1.6.0	Mermaid 12.2.0
Bundle, gzip -9	245 KB	1.532 KB
Render em quente, Chromium headless	~0,44–0,59 ms	~71–79 ms
Primeiro render na página	~17 ms (mount())	~377–431 ms
Render em Node, com parsing	0,56 ms	não testado

A afirmação do tamanho se cumpre: Pele é umas seis vezes mais leve. Em nosso diagrama, a diferença de velocidade foi de umas 135 a 180 vezes, dentro do “até 500” mas longe desse teto. Para uma página de documentação com um punhado de diagramas, a diferença prática não está nos milissegundos, mas em enviar 1,3 MB menos de JavaScript.

O que não faz Pele?

Pele é uma reimplementação, assim que não é idêntico a Mermaid pixel por pixel. Sua página de compatibilidade é clara sobre as diferenças:

• O layout muda. As posições dos nós, os espaços e o traçado das linhas saem do mecanismo próprio de Pele. Se você depende do layout exato de Mermaid, revise seus diagramas no Playground antes de migrar.
• Os temas de Mermaid não se aplicam. themeVariables se ignora e a cor sai do CSS.
• As cores definidas dentro do diagrama são fixas. As que você coloca com style, classDef ou linkStyle não seguem o tema.
• Os rótulos não admitem HTML arbitrário. Os saltos de linha, a negrita e a cursiva sim funcionam.
• Os click com enlace funcionam, mas os callbacks de JavaScript se ignoram.
• Não suporta ZenUML nem plugins externos de Mermaid. supports() lhe diz se um tipo de diagrama está disponível.

É estável o bastante para usá-lo?

Avança rápido. A versão 1.0.4 saiu em 6 de outubro de 2026 e a 1.6.0 em 17 de outubro, e duas das versões intermediárias mudaram a API:

• A 1.5.0 eliminou watch e fit() de mount().
• A 1.6.0 fez que mount() e update() deixassem de lançar exceções ante uma entrada inválida.

Além disso, no momento de publicar essa nota (18 de outubro de 2026), Pele documenta compatibilidade com Mermaid 12.1.0, enquanto que npm já serve Mermaid 12.2.0. Fixe a versão e leia as notas de cada release antes de atualizar. Se um diagrama se vê distinto que em Mermaid, o projeto pede reportá-lo com uma comparação feita no Playground.

É uma boa alternativa a Mermaid.js?

Se você renderiza Mermaid em um site com modo escuro, como uma documentação, um blog ou um portal interno, sim: é uma alternativa direta, porque não o obriga a reescrever nenhum diagrama. Teste-a em uma página: a mudança é um import e um bloco de CSS, e os diagramas começam a seguir seu tema. Se você depende do layout exato de Mermaid, de sua configuração de temas ou de ZenUML, fique com Mermaid por enquanto.

Se o que você procura não é renderizar seu Mermaid mas que um agente lhe gere diagramas com design próprio, revise o que publicamos sobre diagram-design para Claude Code.

---

E você? Em qual parte do seu trabalho você usa diagramas de Mermaid hoje: documentação, READMEs, apresentações ou outra?

Com qual você renderiza seus diagramas de Mermaid?

• Mermaid.js em meu próprio site
• O que traz minha ferramenta (GitHub, Obsidian, meu gerador de docs)
• Eu os exporto a imagem e os colo
• Prefiro outra opção (nos conte qual)

Comente abaixo ou, se este artigo lhe chegou por email, responda diretamente ao email: sua resposta se publica aqui.

Relacionado: Reladraw: a alternativa a Mermaid onde você decide aonde vai cada nó