Diagramas de sereia

O diagrama da sereia traz a criação nativa de diagramas diretamente para o editor. Alimentado pela Mermaid.js, ele permite que você escreva sintaxe de diagramas baseado em texto e veja um diagrama visual renderizado em tempo real – tudo isso sem sair do seu espaço de trabalho de documentação. Diagramas são armazenados como código-fonte editável junto com uma imagem renderizada. Isso significa que seus diagramas são sempre reeditáveis e nunca se tornam capturas de tela estáticas e sem graça.

O que é Mermaid.js?

Mermaid.js é uma biblioteca de diagramas de código aberto que converte a sintaxe do texto simples em diagramas visuais. Em vez de desenhar as formas manualmente em uma ferramenta separada, você descreve o diagrama em texto e a Sereia o renderiza. O Document360 Mermaid.js incorpora diretamente no editor, então todo o fluxo de trabalho acontece sem sair do seu artigo.

Exemplo: As quatro linhas seguintes de texto produzem um fluxograma completo:

graph TD
  A[User submits ticket] --> B{Priority?}
  B -- High --> C[Notify on-call team]
  B -- Low  --> D[Add to backlog]

Quando usar diagramas de sereias

Use diagramas de sereia quando seu conteúdo envolver um processo, relacionamento ou estrutura que seja mais difícil de explicar apenas em palavras. Alguns cenários comuns:

• Um redator técnico documentando um fluxo de aprovação ou jornada de integração
• Um desenvolvedor ou arquiteto ilustrando uma interação com API, arquitetura de sistema ou esquema de banco de dados
• Um gerente de produto mapeando uma jornada do usuário ou visualizando uma linha do tempo de um projeto
• Uma equipe de suporte construindo um fluxograma de solução de problemas ou um caminho de escalonamento

Se você se pegar descrevendo uma sequência de passos ou conexões entre componentes em vários parágrafos, um diagrama quase sempre comunicará isso mais rápido.

Principais benefícios

Inserindo um diagrama da Sereia

Para inserir um diagrama de sereia no seu artigo:

1. Clique dentro do corpo do artigo onde você quer que o diagrama apareça.
2. Digite / (corte para frente) para ativar o menu de comandos de corte.
3. Digite Sereia para filtrar as sugestões.
4. Selecione diagrama da Sereia no menu suspenso.

Escolhendo um modelo

Assim que você aciona a inserção do diagrama da sereia, o modal de seleção do modelo aparece. É aí que você escolhe o ponto de partida para o seu diagrama.

• A partir de um modelo — Navegue ou pesquise entre os 23 modelos disponíveis, depois clique em um. O editor começa com a sintaxe desse template pré-carregada.
• De em branco — Clique em Em Branco para abrir o editor com um painel de sintaxe vazio. Use isso apenas se você já souber a sintaxe da sereia.

Escolhendo um modelo

1. Navegue pelos 23 cartões-modelo ou digite uma palavra-chave (por exemplo, flow, sequence, gantt) na barra de busca.
2. Clique no modelo que corresponde ao que você quer criar.
3. O editor começa com a sintaxe desse template pré-carregada. Edite ainda mais para se encaixar no seu conteúdo.

Usando uma tela em branco

1. Clique na opção Em branco na grade de modelos.
2. O editor começa com um painel de sintaxe vazio.
3. Digite a sintaxe da sua Sereia do zero.

Escrevendo e visualizando seu diagrama

O editor de diagramas da sereia é um espaço de trabalho com dois painéis. O painel à esquerda é onde você escreve a sintaxe da sua sereia. O painel da direita mostra uma prévia ao vivo do diagrama enquanto você digita.

1. Comece com uma declaração do tipo diagrama na primeira linha. Isso diz à Sereia que tipo de diagrama deve renderizar.

   Tipo de diagrama	Primeira linha
   Fluxograma (de cima para baixo)	graph TD
   Fluxograma (da esquerda para a direita)	graph LR
   Diagrama de sequência	sequenceDiagram
   Diagrama de classes	classDiagram
   Gráfico de Gantt	gantt
   Diagrama de estados	stateDiagram-v2
   Diagrama entidade-relacionamento	erDiagram
   Gráfico de pizza	pie
   Mapa mental	mindmap

2. Adicione nós, conexões e rótulos nas linhas seguintes. Cada linha que você digita atualiza imediatamente a prévia à direita.

3. Se você está trabalhando a partir de um modelo, basta substituir o texto provisório por suas próprias etiquetas e conexões.

Se sua sintaxe tiver linhas muito longas (por exemplo, rótulos de nós longos ou descrições detalhadas das arestas), clique no botão Enrolar código abaixo do painel de sintaxe para enrolar linhas longas dentro da largura visível do editor. Isso não afeta a saída do diagrama — apenas muda como o código aparece no editor.

Controles de pré-visualização

O painel direito atualiza instantaneamente conforme você digita. Use os controles de pré-visualização para inspecionar seu diagrama antes de inseri-lo.

Ampliar / Afastar — Clique nos botões de zoom in (+) ou zoom out (−) para aumentar ou diminuir a ampliação da prévia. Use isso para inspecionar partes específicas de um diagrama complexo sem afetar o tamanho real do diagrama no artigo.

Ajustar à tela — Clique no ícone de ajustar à tela ( ) para redefinir o nível de zoom e assim todo o diagrama fica visível na área de visualização sem precisar rolar. Use este para uma revisão final antes de inserir.

Expandir / Colapsar — Clique no ícone expandir ( ) na barra de ferramentas do painel de pré-visualização para esconder o editor de sintaxe e expandir a pré-visualização para preencher toda a largura modal. Clique no ícone de colapsar ( ) para retornar à visualização em painel dividido e continuar editando.

Lidar com erros de sintaxe

Se sua sintaxe não for válida, a prévia mostra um erro e o botão Insert fica desativado.

1. Leia a mensagem de erro. Inclui o número da linha que causa o problema.
2. Corrija essa linha no painel de sintaxe.
3. A prévia é atualizada automaticamente. Uma vez válido, o botão Insert fica ativo.

Erros e correções comuns

:::(Atenção) (

Inserindo o diagrama no artigo

Quando a pré-visualização estiver correta e sem erros, clique em Inserir. O Document360 converte o diagrama em uma imagem SVG e o posiciona na posição do cursor.

Duas coisas são guardadas para cada diagrama:

• A imagem SVG renderizada — visível no artigo e no site da KB.
• A sintaxe da Sereia — armazenada de forma privada, usada quando você edita o diagrama depois.

Gerenciando um diagrama inserido

Clique em qualquer diagrama inserido para abrir o menu de bolhas.

Editando um diagrama existente

Todo diagrama da Sereia que você inserir pode ser editado a qualquer momento, mesmo após a publicação do artigo. A sintaxe original está sempre armazenada.

1. Clique no diagrama e depois clique em Editar diagrama no menu de bolhas.
2. O editor começa com a sintaxe armazenada e uma prévia ao vivo.
3. Faça suas mudanças.
4. Clique em Atualizar. O diagrama do artigo foi substituído; a posição e o alinhamento são preservados.

Se você clicar em Cancelar ou (X) após fazer alterações, aparece um diálogo de confirmação. Clique em Sim, descarte para sair sem salvar, ou Não, volte para continuar editando.

Como os leitores veem seus diagramas

No site da base de conhecimento, diagramas aparecem como imagens SVG estáticas embutidas no artigo. Leitores podem clicar em qualquer diagrama para abrir uma sobreposição em tela cheia, o que é útil para diagramas grandes ou complexos. Controles de edição e sintaxe da fonte nunca são expostos aos leitores.

Melhores práticas

• Um diagrama, uma ideia. Se um fluxograma exceder 15–20 nós, divida-o em um diagrama geral e um diagrama detalhado.
• Sempre adicione uma legenda. Use a opção de legenda no menu de bolhas para rotular cada diagrama. Ajuda os leitores a entender o contexto de uma relance.
• Use SVG para uso externo. SVG é infinitamente escalável sem perda de qualidade. Use PNG apenas quando a ferramenta de destino não suportar SVG.
• Copie para duplicar, não para reconstruir. Use a ação do menu Copiar para duplicar um diagrama. Cada cópia tem sintaxe independente — editar uma não afeta a outra. Colar um diagrama da sereia fora do Document360 (por exemplo, em outra ferramenta) só colará a imagem, não a sintaxe de origem.

Modelos disponíveis

Os modelos a seguir estão disponíveis na tela de Seleção de Modelos. Pesquise por nome ou palavra-chave para encontrar a certa rapidamente.

FAQ