Para migrar a documentação para Markdown, forneça ao agente de IA a pasta de arquivos e deixe‑o executar convert_to_markdown uma vez por arquivo, em lotes revisados. Com GroupDocs.Markdown.Mcp isso acontece localmente no Claude Code, Cursor, GitHub Copilot ou outro cliente MCP, de modo que um arquivo de procedimentos internos nunca é enviado para um serviço de conversão:

Converta tudo na pasta de arquivos para Markdown com front matter e imagens como arquivos. Relate o formato de origem, a contagem de páginas e o tamanho da saída para cada um.

A versão passo a passo com configuração e solução de problemas está na documentação: Como migrar documentação legada para Markdown com IA.

Por que a migração de documentação legada é um trabalho para um agente?

A conversão é mecânica e o trabalho ao redor é repetitivo: listar os arquivos, converter cada um, medir o resultado, encontrar as falhas, repetir. Uma pessoa fazendo isso para centenas de arquivos toma a mesma decisão centenas de vezes. Um agente faz isso de forma consistente e relata cada resultado, enquanto o engine, não o modelo, produz o Markdown. O Markdown salvo não é uma paráfrase dos seus procedimentos.

Este é um runbook. Cada etapa tem um prompt, e a tabela após ele separa o que o agente decide do que o engine faz.

Runbook: como migrar um arquivo Word para Markdown?

  1. Verifique a licença antes de qualquer outra coisa.

    Antes de converter qualquer coisa: qual é o status da licença do servidor markdown?

    get_license_status retorna mode, licensed, consumption e as versões do servidor e do engine. O modo de avaliação processa 3 páginas por documento, portanto uma execução sem licença produz rascunhos plausíveis.

  2. Inventariar o arquivo.

    Liste cada arquivo na pasta de arquivos com seu formato, contagem de páginas e se está criptografado.

    O servidor Markdown não possui ferramenta de listagem de pastas, portanto o agente lista a pasta usando o acesso a arquivos do próprio cliente ou trabalha a partir dos nomes de arquivos que você fornece.

    Então get_document_info retorna fileFormat, pageCount, title, author e isEncrypted para cada arquivo sem convertê‑lo. Arquivos criptografados precisam do parâmetro password.

  3. Execute um piloto de cerca de vinte arquivos.

    Converta os primeiros vinte documentos para Markdown com front matter e imagens como arquivos. Relate o formato, páginas e tamanho da saída para cada um.

  4. Encontre o que não converteu.

    Liste os PDFs cuja conversão produziu menos de 2 KB de Markdown para mais de 5 páginas.

    Esses são quase sempre digitalizações. Não há etapa de OCR neste servidor, portanto eles precisam de outra ferramenta ou permanecem como PDFs indexados por metadados.

  5. Corrija o padrão, então execute o restante em lotes. Vinte arquivos por rodada, com um relatório a cada vez, mantém a execução revisável e o uso medido previsível.

  6. Revise a saída como faria com um pull request. As próximas seções listam o que observar.

Decisão Agente Engine
Quais arquivos converter, em que ordem e tamanho do lote Sim Não
Quais opções passar (images, frontMatter, flavor) Sim, a partir do seu prompt Não
Transformar cabeçalhos, listas e tabelas em Markdown Não Sim
Salvar os arquivos .md e de imagem Não Sim
Detectar um arquivo de 300 páginas que se tornou 4 KB Sim, a partir do relatório Não
Renomear, layout de pastas, chaves extras de front‑matter Sim Não

Quais formatos migram bem?

  • DOCX, DOC, RTF, ODT. A estrutura é explícita na origem, portanto cabeçalhos e tabelas são transferidos de forma limpa.
  • EPUB e MOBI. A estrutura de capítulos mapeia para cabeçalhos Markdown.
  • CHM. Arquivos de ajuda antigos, muitas vezes a única cópia de um procedimento.
  • XLSX. Planilhas tornam‑se tabelas, o que se adequa a listas de parâmetros.

O que a revisão deve verificar?

Peça ao agente para fazer a primeira varredura, então leia uma amostra você mesmo:

Para cada arquivo convertido, liste as imagens que ele referencia e me diga quais arquivos de imagem estão faltando.

Mostre‑me as cinco saídas com o menor tamanho relativo à contagem de páginas.

Imagens escritas com images: "file" ficam ao lado do .md e são referenciadas por caminho relativo, que é o que um repositório de docs espera. Um .md que aponta para imagens que nunca foram gravadas renderiza como imagens quebradas. Em seguida, abra a fonte mais bagunçada e sua saída lado a lado antes de aplicar o padrão ao restante. Faça commit do resultado revisado com seu fluxo de trabalho git normal; o servidor grava arquivos e não toca no seu repositório.

Sessão de exemplo (abreviada)

You:   Convert the first twenty documents in /archive to Markdown with front matter
       and images as files. Report format, pages and output size for each.
Agent: convert_to_markdown (frontMatter: true, images: "file") x 20
       ops-manual-2014.docx   DOCX   88 pages   converted
       install-guide.chm      CHM    41 pages   converted
       supplier-forms-2009.pdf PDF   12 pages   1 KB of Markdown: probably a scan
       Nineteen files look consistent; one scan needs separate handling.

Limites honestos

Sem uma licença, o modo de avaliação processa apenas as primeiras 3 páginas de cada documento, com uma marca d’água de avaliação em cada um. Uma execução de migração nesse estado gera centenas de arquivos curtos que parecem corretos, e a lacuna é encontrada semanas depois quando alguém procura por um procedimento que está faltando. A migração requer uma licença, portanto execute get_license_status antes do primeiro lote. PDFs digitalizados não convertem.

Perguntas Frequentes

Posso converter centenas de documentos Word para Markdown de uma vez?

Sim, mas não em um único prompt. Converta em lotes de cerca de vinte e leia o relatório após cada um, para que uma opção errada seja corrigida antes de ser aplicada a todo o arquivo.

Como migrar a documentação para git com um agente de IA?

O servidor grava arquivos .md e arquivos de imagem na pasta de saída. Você os revisa e faz commit com seu fluxo de trabalho git usual.

A migração docs-as-code envia meus documentos?

Não. GroupDocs.Markdown.Mcp é um processo local, e o arquivo é lido do disco. Apenas o que o agente escreve na conversa chega ao provedor do modelo.

Aprofunde‑se