Como incorporar diagramas de arquitetura ao vivo na documentação, no Notion, no Confluence e no GitHub

Todo diagrama de arquitetura que vira captura de tela em uma wiki começa uma contagem regressiva lenta. O sistema muda, alguém atualiza o original, e a captura no guia de onboarding, no runbook e no documento de design continua do jeito que estava. Seis meses depois, ninguém confia em nenhuma delas.

A solução é simples de dizer: mantenha um único diagrama ao vivo e faça todas as páginas apontarem para ele. Este guia mostra como fazer isso, caso a caso: sites de documentação, Notion, Confluence, READMEs do GitHub e ferramentas de chat, além do que fazer quando uma página não consegue exibir um diagrama ao vivo. Para o fluxo de trabalho completo, veja Diagramas de arquitetura que não envelhecem.

Três formas de mostrar um diagrama

Use as duas primeiras sempre que puder, e exportações só onde nada ao vivo é permitido.

Pegue o link e o código de incorporação

No Archboard, abra o diagrama e escolha Compartilhar:

1. Ative Qualquer pessoa com o link e copie o link de compartilhamento. Quem assiste vê o diagrama ao vivo, sem conta, e não pode editá-lo.
2. No Pro, ative Incorporar e copie o código de incorporação. Ele é assim:

<iframe src="https://getarchboard.app/embed/YOUR_EMBED_TOKEN" width="100%" height="480" style="border:0;border-radius:8px;" allowfullscreen loading="lazy" title="Archboard diagram"></iframe>

Você pode renovar o link ou o código de incorporação a qualquer momento, o que faz o anterior parar de funcionar, ou desativar o compartilhamento, o que desconecta na hora quem está assistindo.

Uma coisa para saber antes de colocar um diagrama ao vivo em uma página pública: quem assiste vê as edições no momento em que acontecem, junto com os nomes e cursores das pessoas com permissão de edição que estão com o diagrama aberto no editor e dos agentes de IA que trabalham nele. Os nomes de quem assiste nunca aparecem.

Sites de documentação

HTML puro, Jekyll, MkDocs e a maioria dos geradores de sites estáticos. Cole o código de incorporação onde o diagrama deve aparecer; o Markdown deles aceita HTML bruto. O Hugo deixa o HTML bruto de fora do Markdown por padrão, então coloque o iframe em um shortcode ou defina markup.goldmark.renderer.unsafe = true na configuração do site.

Docusaurus e outros sites MDX. O MDX espera JSX, então o atributo style precisa ser um objeto e os atributos usam camelCase:

<iframe
  src="https://getarchboard.app/embed/YOUR_EMBED_TOKEN"
  width="100%"
  height="480"
  style={{ border: 0, borderRadius: 8 }}
  allowFullScreen
  loading="lazy"
  title="Checkout service architecture"
/>

Dois pequenos hábitos ajudam quem lê: defina uma altura em que o diagrama caiba sem rolagem e dê a cada iframe um title que descreva o diagrama; os leitores de tela o anunciam.

Notion

Digite /embed, escolha Embed e cole a URL do atributo src do código de incorporação (não a tag iframe inteira). O Notion carrega conteúdos incorporados pelo próprio serviço de embed; se uma página não puder ser exibida diretamente, o Notion mostra um erro no lugar. Nesse caso, cole o link de compartilhamento como marcador: um clique abre o diagrama ao vivo.

Confluence

O Confluence Cloud não aceita HTML bruto nem código iframe no editor. Cole o link de compartilhamento, que o Confluence transforma em um link ou um cartão. Se a sua organização permite apps do Marketplace, um app de macro iframe ou HTML pode mostrar a incorporação na própria página.

O Confluence Data Center tem uma macro HTML que os administradores podem ativar. Ela permite que qualquer pessoa com permissão de edição adicione HTML e JavaScript arbitrários às páginas, por isso muitas organizações a mantêm desligada. Pergunte ao seu admin antes de contar com ela.

READMEs do GitHub e Markdown em repositórios

O GitHub não renderiza iframes em Markdown, então não dá para ter uma incorporação ao vivo em um README. O melhor substituto é um SVG exportado, commitado ao lado do código e com link para o diagrama ao vivo:

[![Checkout architecture](docs/architecture.svg)](https://getarchboard.app/s/YOUR_SHARE_TOKEN)

Quem lê vê a imagem no README, e um clique abre a versão atual. Adicione "atualizou a exportação do diagrama?" ao seu template de pull request e faça commit também da exportação JSON se quiser que as mudanças no diagrama sejam revisadas como dados.

Slack, Teams, Jira e e-mail

Cole o link de compartilhamento. Ele sempre abre a versão atual, então uma mensagem antiga em uma thread não aponta para uma imagem antiga.

Práticas que mantêm tudo funcionando

• Um diagrama, muitos links. Nunca copie um diagrama para um segundo arquivo para "fazer uma versão para a wiki".
• Coloque o título, o responsável e a data da última revisão no canvas. Incorporações e links mostram o canvas, não os metadados da sua página.
• Compartilhe com intenção. Um link ou uma incorporação em uma página pública torna o diagrama público. Mantenha a arquitetura interna em páginas internas e renove o link se ele vazar.
• Use exportações como plano B, não por hábito. Toda exportação é uma cópia que pode ficar desatualizada.

Aqui está a configuração inteira em um único canvas:

Monte no Archboard

Abra qualquer diagrama, escolha Compartilhar e ative o link; no Pro, ative também a incorporação. Se você está começando um diagrama para a sua documentação, os modelos e os exemplos são um jeito rápido de começar, e o diagrama acima usa nove caixas do pack Básico, dentro do plano Free.

Perguntas frequentes

Posso incorporar um diagrama no plano Free? O Free inclui o link de compartilhamento com marca. A incorporação via iframe faz parte do Pro e do Enterprise.

Quem assiste precisa de conta? Não. Qualquer pessoa com o link ou que abra a página com a incorporação pode ver o diagrama ao vivo. Ela não pode editá-lo.

Posso parar de compartilhar depois? Sim. Renove o link ou o código de incorporação para invalidar o anterior, ou desative o compartilhamento para desconectar imediatamente quem assiste.

Um SVG exportado é atualizado quando o diagrama muda? Não. Exportações são cópias. Exporte de novo quando o diagrama mudar, ou use um link ou incorporação sempre que possível.

Por que minha incorporação mostra um erro no Notion ou no Confluence? As duas ferramentas controlam o que pode ser incorporado. Em vez disso, use o link de compartilhamento como marcador ou cartão, ou pergunte ao seu admin sobre apps de incorporação.

Comece grátis — um assento, sem cartão de crédito.