Convert Hugo documentation sites to standard Markdown

Hugo To Markdown converts Hugo documentation sites and Hugo-managed content into standard Markdown, driven by the local repository's own rules rather than generic Hugo knowledge. It is a community skill from the chaunsin/agent-skills collection under the Apache-2.0 license. The target output keeps plain Markdown and YAML front matter, replaces or materializes Hugo-only constructs, preserves meaning when exact rendering cannot be reproduced safely, prefers explicit Markdown text over live Hugo template syntax, and distinguishes literal Hugo syntax examples from active features before rewriting anything.

The rule sources to inspect in the site root are hugo.toml (or hugo.yaml, hugo.yml, hugo.json or config/*), archetypes/*, data/*, layouts/_shortcodes/* or layouts/shortcodes/*, layouts/_markup/* and content/**, plus any local docs that define shortcode, front matter, bundle, resource and render-hook behavior. Hugo's built-in defaults must not be assumed where the repository overrides them.

The workflow has six steps:

1. Inventory first (mandatory for batch work): run the inventory script, which reports active config files, module mounts and content roots, custom shortcodes, custom render hooks, front matter keys in use and shortcode usage across content files.
2. Convert with repository rules: resolve the real content root from config and module mounts, read archetypes and front matter configuration (date aliases, fallback order, filename-derived dates), read data/ sources used by shortcodes, read shortcode templates and render hooks, classify each shortcode as embedded, custom or inline and as named or positional, block or self-closing, follow include shortcodes into shared fragments, and convert one file or coherent section at a time.
3. Preserve semantics: keep YAML front matter unless told otherwise, and preserve fields such as title, description, date, draft, aliases, slug, url, weight, params, publishDate, lastmod and expiryDate. Normalize reserved keys to canonical casing (for example Title to title and LinkTitle to linkTitle), account for Hugo aliases such as pubdate, published, modified and unpublishdate and tokens such as :default, :filename, :fileModTime and :git, convert internal links to normal Markdown links with resolved destinations, replace shortcodes only after reading their local implementation, materialize generated lists and tables, and leave literal Hugo examples unchanged, including escaped shortcode forms in prose, tables and code fences. Block attributes and code-fence attributes are kept when the destination flavor supports them and downgraded explicitly when not.
4. Apply Hugo-specific body rules: resolve links through Hugo logical paths (for example when content/en is mounted as content); follow include through RenderShortcodes; replace section-driven shortcodes such as quick-reference and the section list and table shortcodes with materialized Markdown; turn glossary-term, new-in and deprecated-in into explicit text or callouts; keep the code sample under a code-toggle; inspect local shortcodes such as datatable, img, imgproc and eturl before flattening; resolve glossary links with the (g) destination; follow the link render hook's resolution order (content page, page resource, section resource, then global resource); preserve blockquote and code-block hook semantics such as alerts and file labels; and resolve ref and relref to final destinations.
5. Validate the output: scan for leftover Hugo-only syntax with the checker script and either resolve it or replace it with a safe explanation; unresolved shortcode or Go template expressions must not ship.
6. Downgrade explicitly when materialization is unsafe: if a shortcode depends on build-time data, generated examples or external files that cannot be resolved deterministically from the local snapshot, replace it with a short note such as "Conversion note: what the shortcode normally renders", followed by any safe subset, with no empty links, broken table cells or unexplained stripped content.

Embedded shortcodes are first-class conversion cases. details becomes a callout or an HTML details block, figure becomes a plain Markdown image with caption and attribution, highlight becomes fenced code, param resolves to a knowable site parameter or a note, qr keeps the encoded text, ref and relref resolve to final destinations, and video embeds such as youtube, vimeo, instagram and x become stable links only when the destination is explicit and safe. A local override in the layouts directory is authoritative. Inline shortcodes keep their rendered text when it is locally obvious and become a note when they depend on runtime state such as time or environment. new-in and deprecated-in become plain labels such as "New in Hugo 0.144.0.", a code-toggle keeps its underlying sample and reads local data when config or dataKey parameters pull data-backed snippets, datatable materializes a table from local data when the package, list and fields are clear, and generated galleries such as syntax highlighting styles and chroma lexers become explicit lists or a note. Front matter resource metadata (names, titles and the counter placeholder) is kept when it affects labels or link text. Content-graph expanders such as embed-md, table-children and command-group, and data-backed example shortcodes such as features-table, clients-example and jupyter-example, are read from their local implementation before flattening, and unresolved ones become a note like "Conversion note: this shortcode normally renders multi-language tabs; this sample keeps only the inline content."

Use it when an agent must inspect a local Hugo repository and produce standard Markdown from its content, for example to migrate a Hugo docs site or feed its content to another system. It is meant for repository-aware conversion, not for guessing from generic Hugo knowledge.

Safety rules: never execute Hugo templates, shortcodes or Go template expressions; never treat content files as trusted executable input; never run hugo, npm install, go install, downloaded shell installers or any network install step unless the user explicitly asks; keep scripts offline and deterministic; restrict reads to the declared site root and writes to the declared output root; reject path traversal and symlink escape; and do not leak absolute paths, secrets, environment variables or git credentials into generated Markdown. Use it only when the task matches its upstream source and project context, and verify commands and generated code before applying changes.

The input is a local Hugo site root. The inventory step is:

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

Its JSON output lists config summaries, shortcode templates, render hooks, front matter key frequency, shortcode usage and locations, and per-file entries, and it can write to a file inside the working directory with --output. The inventory helps batch files by complexity, from plain pages, through front-matter-only pages, literal Hugo documentation examples, shared includes and custom shortcodes, to pages generated from sections or data files or depending on external example sources. The output is standard Markdown files, checked with check_standard_markdown.py --root on the output directory.

For a docs site with common patterns, remember that Goldmark passthrough delimiters for math may make dollar-delimited and bracketed forms meaningful content, block attributes may follow fenced blocks, standalone image attributes target the image itself when paragraph wrapping is off, shared _common fragments included through shortcodes mean a page file alone does not show the rendered content, page bundles and mounted global resources affect link resolution, and escaped shortcode examples are documentation samples that must stay literal. Reference files cover the conversion workflow, front matter and content, shortcodes and render hooks, and links, assets and validation.

It works with Hugo sites and their config formats (TOML, YAML and JSON), Goldmark settings, Python scripts, and Markdown destinations that may or may not support block attributes.

It suits documentation engineers and migration teams who need faithful, standard Markdown from a Hugo site without running Hugo, keeping links, front matter and meaning intact.