export

Export hwaro content to other static site generator formats. This is the reverse of hwaro tool import.

Source files can use TOML (+++), YAML (---), or JSON ({...}) front matter. All three formats use the same field mappings and draft filtering. Invalid JSON front matter is reported as an export error instead of being copied into the body.

# Export to Hugo
hwaro tool export hugo

# Export to Jekyll
hwaro tool export jekyll

# Specify output and content directories
hwaro tool export hugo -o ~/hugo-site -c posts

# Include draft content
hwaro tool export jekyll --drafts

# Verbose output
hwaro tool export hugo --verbose

Supported Targets

Options

Re-exporting into the same directory replaces the previous output. That is the normal refresh workflow. When a run replaces pre-existing files, the summary warns with the count, and the JSON manifest marks those rows overwritten (fresh destinations are exported). Use --dry-run to see the full manifest before writing.

JSON Output

{
  "success": true,
  "dry_run": false,
  "exported_count": 2,
  "skipped_count": 0,
  "error_count": 0,
  "files": [
    { "path": "export/_posts/2024-01-01-hello.md", "action": "exported" },
    { "path": "export/about.md", "action": "overwritten" }
  ]
}

files lists every destination written, content assets included, while the counts cover content documents only.

Content Assets

Every non-Markdown file the build publishes from content/ is exported to the same relative path: page-bundle and section files (filtered by [content.files] when it is configured), [content.files] matches anywhere in the tree, and raw .json/.xml files. Files of a draft that is not exported are left out, as the build leaves them out. Hugo reads files beside an index.md/_index.md as bundle resources. In a Jekyll export, a post bundle flattened into _posts/ or _drafts/ has no directory to keep its files in, so they are named in a warning instead.

Field Mappings

Hugo

Every other front-matter key is passed through as a Hugo page param.

Output structure preserves the original directory layout under export/content/. An index.md at the site root, or one with other pages below it, is written as _index.md: Hugo reads index.md as a leaf bundle, which turns every page beneath it into a bundle resource. Leaf bundles (posts/my-post/index.md) keep their name.

Jekyll

Output conventions:

• Dated pages under a top-level posts/ or blog/ section go to _posts/ with YYYY-MM-DD-slug.md filename; every other page (about.md, docs/…) keeps its directory layout, dated or not
• A post moved into _posts/ gets permalink: /<section>/<name>/ (its hwaro address) unless it already has a path or permalink, so rewritten @/ links and inbound URLs keep working instead of moving to Jekyll's /YYYY/MM/DD/name.html
• Draft posts (under posts/ or blog/, exported with --drafts) go to _drafts/ without date prefix
• redirect_from only redirects when the jekyll-redirect-from plugin is enabled under plugins: in the Jekyll _config.yml (it is allow-listed, not on by default, on GitHub Pages)
• Section index files (_index.md, and translations such as _index.ko.md) become index.md (index.ko.md) pages
• Frontmatter is converted from TOML, YAML, or JSON to YAML (---)
• A [taxonomies] table is hoisted to top-level keys, since neither Hugo nor Jekyll reads taxonomy membership from a nested table. An explicit top-level key of the same name wins, matching how the build resolves the two

Internal Links

Internal links using the @/ prefix are automatically converted to absolute paths:

<!-- Hwaro -->
[About](@/about/_index.md)

<!-- Exported -->
[About](/about/)

A section _index.md and a page-bundle index.md both map to their directory URL. Links shown inside code blocks or inline code spans are left exactly as written, since the build does not resolve them there either.

A link to a translation (@/about.ko.md, with ko declared under [languages]) exports to Hugo as /ko/about, the URL Hugo and the build both serve it at. Jekyll has no languages, so there it points at the exported file (/about.ko, and /docs/index.ko for @/docs/_index.ko.md).

Example Output

hwaro: export hugo
source: content
output: export
exported: 38 files, 4 skipped

An errors count is appended only when errors occurred. In a color terminal the same report renders as an hwaro export heading with aligned rows and a ✦ exported outcome line.