Hugo para Markdown

Quando Usar

Use esta habilidade quando precisar converter sites de documentação Hugo e conteúdo gerenciado pelo Hugo em Markdown padrão. Use quando o Agente precisar inspecionar um repositório Hugo local, ler arquivos hugo.toml ou de configuração, content/, archetypes/, layouts/_shortcodes/, layouts/_markup/, e conteúdo de documentação relacionado, e então produzir Markdown...

Visão Geral

Use esta habilidade quando a saída Markdown precisar ser derivada do site Hugo local, não adivinhada a partir de conhecimento genérico do Hugo. As regras de conversão são a combinação do comportamento oficial do Hugo e a configuração própria do repositório, templates de shortcode, render hooks, archetypes e convenções de conteúdo.

A saída alvo é Markdown padrão:

• Mantenha Markdown simples e front matter YAML.
• Substitua ou materialize construtos exclusivos do Hugo.
• Preserve o significado quando a renderização exata não for reproduzível com segurança.
• Prefira texto Markdown explícito em vez de sintaxe de template Hugo ativa.
• Distinga exemplos de sintaxe Hugo literal de recursos Hugo ativos antes de reescrever qualquer coisa.

Base Oficial

Trate a configuração e os templates Hugo próprios do repositório como o conjunto de regras primário. Para qualquer site em conversão, inspecione estas fontes de regras na raiz do site fornecida pelo usuário:

• hugo.toml (ou hugo.yaml, hugo.yml, hugo.json, ou config/*)
• archetypes/*
• data/*
• layouts/_shortcodes/* ou layouts/shortcodes/*
• layouts/_markup/*
• content/**

Leia também qualquer documentação local que defina o comportamento de shortcode, front matter, bundle, resource e render-hook.

Não assuma padrões embutidos do Hugo se o repositório os substituir localmente.

Fluxo de Trabalho

1. Inventariar o site antes de converter arquivos

Sempre inspecione as regras em nível de site primeiro.

python3 scripts/inventory_hugo_rules.py --site-root /path/to/hugo-site

Exemplo de invocação para o site do usuário:

python3 skills/hugo-to-markdown/scripts/inventory_hugo_rules.py \
  --site-root /path/to/your-hugo-site

Esta etapa de inventário é obrigatória para trabalho em lote. Ela identifica:

• arquivos de configuração ativos
• montagens de módulos e raízes de conteúdo
• shortcodes personalizados
• render hooks personalizados
• chaves de front matter vistas no conteúdo
• uso de shortcode em arquivos de conteúdo

2. Converter com regras do repositório, não com heurísticas genéricas

Leia references/conversion-workflow.md antes de alterar os arquivos. Em seguida:

1. Resolva a raiz de conteúdo real a partir de hugo.toml, config.* e montagens de módulos.
2. Leia os archetypes para entender a forma esperada do front matter.
3. Leia a configuração do front matter para entender aliases de data, ordem de fallback, datas derivadas de nome de arquivo e outros metadados inferidos.
4. Leia as fontes de dados do site em data/ quando shortcodes ou partials puxam conteúdo estruturado delas.
5. Leia os templates de shortcode personalizados em layouts/_shortcodes/ ou layouts/shortcodes/.
6. Classifique cada shortcode encontrado como embutido, personalizado ou inline, e verifique se ele usa argumentos nomeados ou posicionais, sintaxe de bloco ou sintaxe de fechamento automático.
7. Leia os render hooks em layouts/_markup/.
8. Verifique se o repositório já define templates e partials de exportação voltados para Markdown ou JSON; se o fizer, use-os como evidência de como o próprio site faz downgrade de construtos do Hugo.
9. Siga shortcodes no estilo include para arquivos de conteúdo referenciados quando o site de documentação compõe conteúdo de fragmentos compartilhados.
10. Converta um arquivo ou uma seção coerente de cada vez.

3. Preservar semântica durante a conversão

Use estas regras por padrão:

• Mantenha o front matter YAML, a menos que o usuário peça explicitamente por Markdown sem front matter.
• Preserve campos centrais como title, description, date, draft, aliases, slug, url, weight e params aninhados quando eles ainda carregam significado.
• Preserve metadados de publishDate, lastmod, expiryDate e recursos de página quando eles ainda afetam o significado ou o roteamento downstream.
• Normalize chaves reservadas de front matter do Hugo para seus nomes canônicos quando o repositório mistura maiúsculas e minúsculas, por exemplo, Title para title, Description para description e LinkTitle para linkTitle.
• Considere aliases e tokens de front matter do Hugo antes de decidir que um campo não está em uso. A documentação oficial do Hugo reconhece aliases como pubdate, published, modified e unpublishdate, além de tokens como :default, :filename, :fileModTime e :git.
• Converta links internos do Hugo para links Markdown normais com destinos resolvidos.
• Substitua shortcodes do Hugo por Markdown simples, HTML ou notas explícitas somente após ler a implementação local do shortcode.

…