Guia Completo do PlantUML: Título, Cabeçalho, Rodapé, Nota, Legenda e Legenda

Este guia abrange os seis elementos mais utilizados de texto e anotação no PlantUML. Em todos os exemplos, aplico as convenções da casa: skinparam defaultFontSize 14 e skinparam defaultFontColor #333333 no topo do arquivo.

Uma rápida orientação sobre onde cada elemento fica em relação ao corpo do diagrama:

1. Título

O título do diagrama fica centralizado no topo. Ele suporta marcação em linha (<tamanho>, <negrito>, <cor>, <sublinhado>, <itálico>) e uma forma de múltiplas linhas.

Forma simples:

título Serviço de Processamento de Pedidos

Forma de múltiplas linhas com formatação:

title
<size=20><b>Serviço de Processamento de Pedidos</b></size>
<size=14><color=#555555>Diagrama de Contexto - v1.0</color></size>
endtitle

Com um padrão de subtítulo: O PlantUML não possui uma palavra-chave dedicada para subtítulo, então simule-o com uma segunda linha menor, conforme mostrado acima.

Armadilhas comuns

• título sem fim título está ok apenas para uma única linha. Se você escrever qualquer coisa na próxima linha, o PlantUML a tratará como parte do título apenas se você abriu um bloco com fim título.

• As tags HTML em linha devem ser fechadas (<b>...</b>) ou a renderização será imprevisível.

• O título faz parte do diagrama, então ele aparece nas exportações — não o duplique na legenda do nome do arquivo.

2. Cabeçalho

O cabeçalho é renderizado acima o corpo do diagrama, separado dele. Use-o para contexto organizacional, banners de classificação ou IDs de documento. Forma de uma única linha ou bloco:

header Comitê de Revisão de Arquitetura - Interno

header
<font color=#777777 size=12>Comitê de Revisão de Arquitetura</font>
endheader

Quando usar cabeçalho vs. título: o título descreve o que o diagrama é; o cabeçalho descreve o contexto do documento ao qual pertence (org, confidencialidade, lançamento). Mantê-los separados permite carimbar muitos diagramas com o mesmo cabeçalho.

3. Rodapé

O rodapé espelha o cabeçalho na parte inferior. Ideal para autoria, ferramentas e carimbos de data/hora.

footer Preparado usando Visual Paradigm VPasCode

footer
<font color=#777777 size=11>Preparado usando Visual Paradigm VPasCode - Gerado em 2025</font>
endfooter

Dica: O PlantUML substitui %date% (e %time%) dentro do texto de cabeçalho/rodapé/título, o que é útil para exportações carimbadas:

footer Renderizado %date%

4. Legenda

Uma legenda é uma única linha posicionada diretamente abaixo do diagrama. É o local idiomático para numeração de figuras em documentos (emparelha-se naturalmente com um título acima).

legenda Figura 1. Serviço de pedidos e seus colaboradores

Ao contrário de título/cabeçalho/rodapé, legenda ocupa uma única linha — sem fim da legenda bloco é necessário ou esperado. Mantenha-o curto e no estilo de referência.

5. Legenda

A legenda é uma chave em caixa renderizada em um canto do diagrama. Ela aceita texto rico e sintaxe simples de tabela (| | células). A posição é controlada por uma palavra-chave: topo, base, esquerda, direita, ou centro.

legenda direita
  |= Estado |= Significado |
  | Novo | Criado, não pago |
  | Pago | Pagamento capturado |
  | Enviado | Entregue ao transportador |
fim da legenda

Opções de posicionamento

legenda topo esquerdo
  Seta sólida = chamada síncrona
  Seta tracejada = evento assíncrono
fim da legenda

Quando usar uma legenda versus uma nota:uma legendadecodifica a notação usada em todoo diagrama (o que um símbolo, estilo de linha ou cor significa). Uma notafaz comentários sobre um elemento específico. Se o seu leitor precisar consultar um símbolo em mais de um lugar, promova-o para uma legenda.

6. Nota

As notas vinculam comentários a um único elemento ou flutuam livremente. Existem três estilos de chamada.

Nota de uma linha vinculada a um elemento:

note top of Order : Nota flutuante de uma linha

Nota de várias linhas vinculada a um elemento:

note right of Order
  Nota de várias linhas
  com **formatação** livre
end note

Nota independente (flutuante): atribua a ela um alias para que possa ser vinculada ou posicionada posteriormente.

note "Nota independente ancorada via alias" as N1

Palavras-chave de posicionamento para notas vinculadas: topo, base, esquerda, direita de <elemento>. Você pode combinar duas direções em versões mais recentes (por exemplo, note top left of), mas o posicionamento em uma única direção é o mais portátil.

Armadilhas

• A forma de uma única linha após : é apenas para uma linha — use o end note bloco para várias linhas.

• Dentro de end note blocos, marcação inline padrão e até mesmo diagramas/diagramas secundários incorporados funcionam; evite aspas soltas não escapadas-- que alguns analisadores leem como um separador.

7. Juntando Tudo

O seguinte valida limpa e demonstra todos os elementos em um único diagrama. Observações: cabeçalho/rodapé/título/legenda enquadram o diagrama de fora para dentro, enquanto o legenda e notavivem dentro da tela do diagrama.

@startuml
skinparam defaultFontSize 14
skinparam defaultFontColor #333333

cabeçalho Architecture Review Board - Internal

título Order Processing Service - Context Diagram v1.0

legenda Figura 1. Serviço de pedidos e seus colaboradores

rodapé Preparado usando Visual Paradigm VPasCode

ator Cliente
componente WebApp
componente OrderSvc
database OrderDB

Cliente --> WebApp
WebApp --> OrderSvc
OrderSvc --> OrderDB

nota à direita de OrderSvc
  Valida o pedido,
  depois persiste no OrderDB.
fim nota

legenda à direita
  |= Seta |= Significado |
  | --> | Chamada síncrona |
  | ...> | Evento assíncrono |
fim legenda
@enduml

Documentação e Renderização com Visual Paradigm VPasCode

Cole qualquer um dos completos @startuml … @endumlarquivos acima no Visual Paradigm VPasCode e ele renderizará o diagrama, aplicará o tema VP e permitirá exportar para PNG/SVG/PDF. O tema VP também pode ser aplicado explicitamente no topo de um diagrama:

!include https://static.visual-paradigm.com/web/resources/plantuml-stdlib/themes/vp.puml
skinparam vpDiagramType ComponentDiagram

Você pode visualizar e renderizar esses online em https://www.vpascode.com. Organize sua estrutura base de forma consistente — título e legenda para a identificação da figura, cabeçalho/rodapé para o contexto do documento, legenda para a decodificação da notação, nota para comentários por elemento — e seus diagramas serão lidos como um conjunto coerente e profissionalmente publicado.

This post is also available in English, Español, Français, Bahasa Indonesia, 日本語, Polski, Ру́сский, Việt Nam, 简体中文 and 繁體中文.