Modernizando uma Base de Conhecimento Legada com Markdown, Mermaid e IA

Resumo executivo

Este estudo de caso documenta a modernização da base de conhecimento de um portal corporativo privado construído sobre o HESK.

O HESK já oferecia o núcleo validado de help desk, autenticação, categorias, permissões e publicação de artigos. A base de conhecimento, porém, tratava HTML como o principal formato de autoria e armazenamento. Esse modelo continuava funcional para o navegador, mas se tornava menos adequado conforme os artigos cresciam, passavam a incluir procedimentos técnicos, blocos de código, tabelas, fluxogramas e colaboração com ferramentas de inteligência artificial.

Uma reescrita do Portal ou a conversão automática de todo o acervo criaria risco sem benefício proporcional. A solução adotada foi incremental: artigos existentes permanecem em HTML, enquanto novos artigos podem usar Markdown como fonte canônica. O Portal identifica o formato de cada registro, aplica o pipeline apropriado e entrega HTML sanitizado para visualização.

O projeto também incorporou Mermaid para diagramas técnicos, um editor com preview server-side e um contrato de integração que permite a agentes de IA consultar, criar e acrescentar seções em Markdown sem precisar manipular HTML de apresentação.

O resultado é uma base de conhecimento híbrida, compatível com o legado e preparada para colaboração entre pessoas, sistemas e agentes de IA.

Contexto

O Portal evoluiu a partir do HESK para atender múltiplos fluxos operacionais. A base de conhecimento acompanha essa evolução: além de respostas curtas de suporte, passou a concentrar procedimentos, diagnósticos, runbooks e documentação de projetos de infraestrutura.

Nesse cenário, um artigo técnico pode conter:

• hierarquia de títulos;
• sequências operacionais;
• listas de verificação;
• comandos de terminal;
• consultas SQL;
• tabelas de decisão;
• avisos e critérios de encerramento;
• diagramas que explicam estados ou dependências.

Essas estruturas podem ser representadas em HTML, mas editar diretamente a marcação mistura conteúdo, apresentação e detalhes do editor. Isso também torna atualizações automatizadas mais frágeis: uma ferramenta precisa preservar tags, atributos e estruturas que não fazem parte da mensagem técnica.

A necessidade não era eliminar HTML do navegador. Era estabelecer uma fonte mais simples, previsível e interoperável antes da renderização.

Problema

O modelo anterior apresentava quatro dificuldades principais.

HTML era simultaneamente fonte e apresentação

O conteúdo persistido já carregava decisões de renderização. Pequenas alterações podiam introduzir marcação inconsistente, entidades escapadas ou diferenças entre o editor e a página publicada.

Documentação técnica extensa era difícil de manter

Blocos de código, tabelas e documentos hierárquicos exigiam mais esforço de edição. O conteúdo também era menos portável para revisão, comparação e reaproveitamento em outras ferramentas.

Fluxos visuais não possuíam uma representação textual nativa

Diagramas baseados somente em imagens são difíceis de corrigir e manter junto ao artigo. Mermaid permite que a definição do fluxo permaneça versionável e editável como texto.

O conector de IA recebia uma representação orientada ao navegador

Modelos de IA conseguem interpretar HTML, mas esse não é necessariamente o melhor contrato para autoria. Tags de apresentação aumentam o ruído, e alterações parciais podem quebrar a estrutura do documento. Para colaboração segura, o agente precisava saber qual era o formato canônico e receber o Markdown original.

Objetivos

O projeto foi definido com objetivos explícitos:

1. preservar todos os artigos HTML existentes;
2. adotar Markdown somente para novos artigos;
3. manter os dois formatos na mesma base;
4. renderizar CommonMark/GFM no servidor;
5. sanitizar o HTML antes de exibi-lo;
6. suportar Mermaid sem dependência de CDN em produção;
7. oferecer um editor técnico com preview confiável;
8. garantir paridade visual entre preview e leitura;
9. permitir leitura e autoria por agentes de IA;
10. impedir sobrescritas silenciosas durante edições concorrentes;
11. manter rascunho e revisão humana antes da publicação;
12. implantar a mudança em fases pequenas e reversíveis.

Restrições

O acervo legado não poderia ser invalidado

Os artigos existentes continuavam úteis e não justificavam uma migração obrigatória. Qualquer solução precisava manter o pipeline HTML anterior disponível.

O Portal continuaria baseado no HESK

A base de autenticação, autorização e publicação já estava integrada ao restante da plataforma. O objetivo era estender uma capacidade específica, não criar outro sistema de conhecimento desconectado.

Conteúdo interno não poderia depender de serviços públicos

Diagramas e renderização deveriam funcionar mesmo quando uma CDN estivesse indisponível ou bloqueada. Definições internas também não deveriam ser enviadas a terceiros para renderização.

A visualização não poderia confiar no conteúdo de entrada

Markdown não é uma fronteira de segurança por si só. O resultado renderizado ainda precisava passar por sanitização e políticas explícitas antes de chegar ao navegador.

A IA não deveria publicar alterações irrestritas

Criação automatizada precisava respeitar rascunhos, permissões, versão do conteúdo e revisão humana.

Arquitetura sanitizada

Hosts, endereços, credenciais, nomes internos e detalhes proprietários foram omitidos.

A arquitetura preserva uma distinção essencial: Markdown é a fonte de autoria, enquanto HTML sanitizado é a representação de leitura no navegador.

Modelo de conteúdo híbrido

Cada artigo possui um formato explícito. Isso permite que o mesmo fluxo de navegação trate registros antigos e novos sem inferir o tipo a partir do conteúdo.

O projeto não converte artigos HTML automaticamente. Essa decisão evita alterações visuais inesperadas e mantém o escopo da mudança controlado. Um artigo legado só precisa ser migrado se houver um motivo operacional e uma revisão específica.

Pipeline de renderização e segurança

O fluxo de um artigo Markdown segue etapas separadas:

1. o Portal lê o formato declarado;
2. o Markdown é processado por um renderer CommonMark/GFM;
3. o HTML intermediário passa por sanitização;
4. blocos Mermaid autorizados recebem marcação controlada;
5. a biblioteca Mermaid local transforma o texto do diagrama em SVG;
6. estilos compartilhados compõem a visualização final.

O sanitizador continua necessário porque Markdown pode conter links, atributos ou HTML incorporado dependendo da configuração do parser. O renderer não é tratado como uma barreira de segurança completa.

Também foi adotada uma política de falha segura para diagramas: um erro de sintaxe Mermaid não deve executar conteúdo arbitrário nem comprometer o restante do artigo. O texto continua recuperável para correção pelo autor.

Editor Markdown

A área administrativa ganhou um modo específico para artigos Markdown. O formato fica explícito e bloqueado durante a edição, reduzindo o risco de uma conversão acidental entre Markdown e HTML.

O editor oferece atalhos para:

• títulos;
• negrito;
• listas;
• links;
• blocos de código cercados;
• tabelas;
• diagramas Mermaid.

O preview é produzido no servidor pelo mesmo domínio responsável pela renderização final. Essa escolha evita manter dois parsers independentes, um em JavaScript e outro em PHP.

Um problema importante apareceu durante a homologação: o preview podia parecer correto, mas a visualização publicada aplicava outro contexto de estilos. A correção foi compartilhar a mesma classe de conteúdo, regras tipográficas e comportamento de componentes entre as duas superfícies. O preview passou a representar o resultado real, não apenas uma aproximação.

Mermaid local e documentação como código

Mermaid permite armazenar o diagrama junto ao procedimento:

• mudanças podem ser revisadas como texto;
• o fluxo acompanha o artigo;
• a IA pode propor ou corrigir a definição;
• não é necessário editar uma imagem para alterar um nó;
• a definição permanece pesquisável.

A biblioteca é fornecida como asset local do Portal. Isso reduz dependência operacional de terceiros, evita enviar o conteúdo do diagrama a uma CDN e fixa a versão executada em homologação e produção.

A implementação local também exigiu disciplina de build. Durante a primeira prova, o HTML e o inicializador carregavam, mas o asset Mermaid ainda não existia no diretório público. O navegador exibia apenas o texto do fluxograma. Esse comportamento reforçou a necessidade de validar não somente o código-fonte, mas também os artefatos efetivamente entregues pelo deploy.

Contrato para agentes de IA

O conector passou a declarar a representação de maneira explícita. Uma resposta sanitizada para um artigo Markdown segue este princípio:

{
  "content_format": "markdown",
  "content_markdown": "## Procedimento\n\nConteúdo técnico...",
  "content_hash": "versao-do-conteudo"
}

Quando o formato é Markdown, o agente recebe a fonte em content_markdown, e não precisa reconstruí-la a partir do HTML renderizado.

Esse contrato melhora a colaboração porque o agente pode:

• compreender a hierarquia sem ruído de apresentação;
• preservar listas, tabelas e blocos de código;
• produzir Mermaid como texto;
• acrescentar uma seção sem reescrever a página inteira;
• devolver conteúdo adequado ao mesmo renderer usado pelo Portal;
• identificar qual versão foi utilizada como base da alteração.

A mudança não assume que IA seja incapaz de ler HTML. Ela reconhece que uma representação semântica, estável e explicitamente tipada é um contrato melhor para leitura e autoria automatizadas.

Concorrência e proteção contra sobrescrita

O content_hash funciona como controle de concorrência otimista.

Antes de atualizar um artigo, o agente trabalha sobre uma versão conhecida. Se uma pessoa ou outro processo alterar o documento no intervalo, o hash deixa de corresponder e a operação pode ser recusada. O conteúdo mais recente precisa ser consultado antes de uma nova tentativa.

Esse mecanismo protege um cenário simples, mas importante:

1. um administrador abre e modifica o artigo;
2. um agente ainda possui a versão anterior;
3. o agente tenta acrescentar uma seção;
4. o Portal detecta o conflito em vez de apagar a edição humana.

Rascunho e governança humana

O conector pode preparar novos artigos em Markdown, mas o fluxo privilegia a criação como rascunho.

A revisão humana verifica:

• precisão técnica;
• ausência de dados confidenciais;
• comandos potencialmente destrutivos;
• clareza dos pré-requisitos;
• legibilidade de tabelas e diagramas;
• categoria e público corretos;
• critérios de validação e recuperação.

Assim, a IA atua como autora assistida e consumidora do conhecimento, não como publicadora irrestrita.

Implantação em fases

A mudança foi dividida em etapas com homologação entre merges:

1. prova local de CommonMark, sanitização e Mermaid;
2. extensão do modelo de dados para distinguir os formatos;
3. leitura híbrida com compatibilidade para HTML;
4. editor Markdown e preview server-side;
5. integração do conector para consulta e preview;
6. criação de rascunhos e atualizações controladas;
7. paridade visual entre edição e leitura;
8. documentação técnica, runbooks e encerramento.

A migration foi aplicada pelo processo de deploy, e cada fase só avançou depois que CI, publicação e validação funcional ficaram verdes.

Problemas encontrados durante a homologação

Os incidentes de teste ajudaram a validar camadas diferentes do sistema.

Testes CLI comprovaram bibliotecas e contratos isolados. O navegador encontrou problemas de assets, rotas e JavaScript. A homologação verificou o comportamento integrado. CI e deploy confirmaram que o ambiente poderia reproduzir a solução.

Resultados

Compatibilidade sem migração forçada

Todo o conteúdo HTML anterior continuou disponível, enquanto novos artigos passaram a usar uma fonte mais adequada para documentação técnica.

Melhor experiência de autoria

Títulos, código, tabelas e fluxogramas podem ser escritos em um formato legível mesmo antes da renderização.

Preview confiável

A visualização administrativa e a página publicada compartilham o mesmo comportamento tipográfico e de componentes.

Conhecimento acessível a agentes

O conector fornece Markdown original e metadados de formato, permitindo leitura e alterações estruturadas sem manipulação frágil de HTML.

Diagramas mantidos junto ao conteúdo

Mermaid transformou fluxos visuais em texto editável, pesquisável e revisável.

Entrega operacionalmente validada

Migrations, dependências, testes, CI, deploy e homologação foram concluídos antes do encerramento da implementação.

Nenhum percentual de produtividade, redução de tempo ou qualidade de respostas de IA é afirmado porque essas medições ainda não foram preparadas para publicação.

Decisões de segurança

Os principais controles foram:

• HTML legado permanece no pipeline já conhecido;
• Markdown é renderizado no servidor antes da leitura;
• o HTML derivado passa por sanitização;
• Mermaid utiliza configuração controlada e asset local;
• o navegador não recebe segredos do conector;
• ações de criação e edição respeitam autenticação e autorização;
• rascunhos preservam revisão humana;
• hashes evitam sobrescritas silenciosas;
• respostas de erro não expõem stack traces ou configuração;
• exemplos públicos omitem endpoints, credenciais, identificadores reais e topologia.

Trade-offs

A arquitetura híbrida adiciona complexidade: o Portal precisa manter dois caminhos de leitura e reconhecer qual fonte pode ser editada.

Essa complexidade foi aceita porque elimina uma migração de alto risco e permite que o valor seja entregue progressivamente. O custo é controlado por um discriminador explícito de formato e testes para ambos os caminhos.

Também foi decidido não usar um editor visual completo para Markdown. A interface privilegia previsibilidade e autoria técnica. Usuários precisam conhecer algumas convenções, mas o preview e os atalhos reduzem essa barreira.

Lições aprendidas

Modernizar não exige apagar o legado

Preservar HTML e adicionar um formato canônico novo foi mais seguro do que tentar normalizar todo o acervo em uma única entrega.

Fonte e apresentação devem ter responsabilidades diferentes

Markdown é adequado à autoria e intercâmbio. HTML continua sendo a saída correta para o navegador. Tratar um como substituto absoluto do outro teria apenas movido o problema.

Preview só é confiável quando compartilha o pipeline final

Dois renderers ou dois contextos visuais tendem a divergir. Paridade precisa ser uma característica arquitetural, não uma conferência manual ocasional.

APIs preparadas para IA precisam de semântica explícita

Um campo genérico de conteúdo é insuficiente quando múltiplos formatos coexistem. Formato, fonte canônica, versão e estado de publicação fazem parte do contrato.

Testes locais não representam o deploy completo

Um parser validado por CLI não comprova a existência de assets, o bootstrap da rota web, a resposta JSON ou os estilos aplicados na página real.

IA útil ainda precisa de limites operacionais

Rascunhos, permissões, sanitização e controle de concorrência tornam a automação mais confiável sem remover responsabilidade humana.

Limitações

• artigos HTML antigos ainda carregam as limitações do modelo anterior;
• a conversão de um artigo legado exige revisão individual;
• Markdown não substitui validação da precisão técnica;
• diagramas Mermaid continuam sujeitos a erros de sintaxe;
• a experiência atual é orientada a autores técnicos;
• métricas de adoção e qualidade ainda precisam ser acumuladas;
• o Portal permanece acoplado a convenções históricas do HESK.

Próximos passos

A implementação principal está concluída. Evoluções possíveis incluem:

• medir adoção de Markdown e incidência de correções após a revisão;
• adicionar linting de Markdown e Mermaid antes da publicação;
• ampliar histórico e comparação de revisões;
• criar templates por tipo de procedimento;
• indexar semanticamente apenas conteúdo autorizado;
• melhorar acessibilidade de diagramas;
• avaliar migração voluntária de artigos HTML mais utilizados;
• expandir testes negativos de sanitização e concorrência.

Conclusão

O projeto começou como uma melhoria de formatação, mas evoluiu para uma mudança no modelo de conhecimento do Portal.

Ao preservar o HESK e os artigos existentes, introduzir Markdown como fonte canônica, renderizar Mermaid localmente e fornecer um contrato explícito para agentes de IA, a solução transformou a base de conhecimento em um recurso mais estruturado, portável e reutilizável.

O mesmo conteúdo agora pode servir à leitura humana, à manutenção técnica, à criação de runbooks e à colaboração assistida por IA sem abandonar o ambiente operacional já validado.

Declaração de confidencialidade

Este estudo utiliza arquitetura e exemplos sanitizados. Ele não contém código privado do Portal ou do conector, credenciais, endereços, nomes de hosts, usuários, artigos internos, identificadores reais, nomes de bancos ou topologia de produção.