Convert Hugo documentation sites to standard Markdown

This skill converts Hugo documentation sites and Hugo-managed content into standard Markdown by deriving the conversion rules from the specific repository's own configuration rather than generic Hugo knowledge. It treats hugo.toml/hugo.yaml/config/*, archetypes/*, data/*, layouts/_shortcodes/* or layouts/shortcodes/*, layouts/_markup/*, and content/** as the primary rule sources, since a repo's local overrides take precedence over Hugo's built-in defaults. The workflow starts with a mandatory inventory step - running scripts/inventory_hugo_rules.py --site-root <path> to identify active config files, module mounts, custom shortcodes, custom render hooks, and front-matter keys actually used in content - before converting anything. Conversion then proceeds by resolving the real content root from config and module mounts, reading archetypes for expected front-matter shape, reading front-matter configuration for date aliases and fallback order (Hugo recognizes aliases like pubdate/published/modified/unpublishdate and tokens like :default/:filename/:fileModTime/:git), classifying each shortcode as embedded/custom/inline with its real argument convention, reading render hooks, checking for any Markdown/JSON export templates the site already defines, following include-style shortcodes into referenced fragments, and converting one file or coherent section at a time. Semantic-preservation rules cover keeping YAML front matter and core fields (title, description, date, draft, aliases, slug, url, weight, params) unless told otherwise, normalizing mixed-case reserved keys to canonical form, converting internal links to resolved Markdown links, materializing shortcode-generated lists/tables from real data, and explicitly leaving literal Hugo syntax examples unchanged when a document is documenting Hugo rather than invoking it (including escaped forms like {{</* foo */>}}). It names common Hugo-docs-site shortcode patterns to check case-by-case - include, quick-reference, render-list-of-pages-in-section, glossary-term, code-toggle, datatable, img/imgproc, eturl, and others - plus link render-hook resolution order (content page, page resource, section resource, then global resource) and glossary shorthand (g) links. After conversion, scripts/check_standard_markdown.py --root <output> scans for leftover active Hugo syntax outside code fences, which must be either fully resolved or replaced with an explicit textual note - never shipped unresolved. When a shortcode depends on build-time data or external sources that can't be resolved deterministically from the local snapshot, it's downgraded to a short > Conversion note: explaining what it normally renders, preserving any safe subset (an image URL, a resolved list) rather than leaving broken or silently stripped content.

Use it when an agent needs to inspect a local Hugo repository - its config, content/, archetypes, shortcode layouts, and render hooks - and produce Markdown output that must be derived from that specific site rather than guessed from generic Hugo knowledge. Do NOT execute Hugo templates, shortcodes, or Go template expressions, and never run hugo, npm install, go install, or any network install step unless the user explicitly asks - conversion scripts must stay offline and deterministic, restricted to the declared site root for reads and the declared output root for writes, rejecting path traversal or symlink escape.

Inputs: a local Hugo site root (config files, content/, archetypes/, data/, shortcode and render-hook layouts). Outputs: standard Markdown files with preserved YAML front matter and semantics, an inventory report of the site's active config/shortcodes/render-hooks/front-matter keys, and a post-conversion validation report flagging any leftover active Hugo syntax that still needs resolving or an explicit conversion note.

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

Built around two bundled Python scripts - inventory_hugo_rules.py for site-rule discovery and check_standard_markdown.py for post-conversion residue validation - plus four reference files covering the conversion workflow, front-matter/content conventions, shortcodes and render hooks, and link/asset validation.

Documentation engineers and agents migrating a Hugo-based docs site to plain Markdown who need the conversion to reflect that specific repo's real shortcodes, render hooks, and front-matter conventions rather than generic Hugo assumptions.