Awesome Hugo is a collection of open-source scripts from the Hugo Blox team for upgrading and managing Hugo and Hugo Blox static sites, automating batch edits to Markdown content and front matter.
What is Awesome Hugo?
Awesome Hugo is a GitHub repository that bundles five utilities for migrating and restructuring Hugo and Hugo Blox sites. It takes existing site files as input — content pages, front matter, and homepage section bundles — and outputs transformed files that follow newer version conventions. The scripts cover the migration paths from Academic v2.4.0 through Hugo Blox v0.8.0, and are maintained by Hugo Blox under the MIT license.
Key Features
- singular2plural — Upgrades a site to Hugo Blox v0.8.0 content type conventions, supports a
--dry-runmode, and adds helpful Netlify redirects. - refactor-pages-to-page-bundles.sh — Converts page files from
content/<section>/X.mdtocontent/<section>/X/index.md, assisting the Academic v2.4.0 → v3.0.0 migration. - refactor_pages_convert_TOML_to_YAML.py — Converts all front matter from TOML to YAML for broader editor compatibility; requires Python 3.8+ and Poetry, with
pyyamlandtomlas dependencies. - refactor-widget-bundles-as-headless.sh — Adds
headless: trueto homepage section bundles for the Academic v4.1 → v4.2 upgrade. - refactor_page_bundles_to_pages.sh — Reverts homepage page bundles back to individual page files, mainly for testing or downgrades; it does not offer a
--dry-runflag.
Who is it for?
- Hugo Blox and Academic site maintainers who need to upgrade their content structure across major version changes and want automated scripts to perform the repetitive rewrites.
- Static site developers working with Markdown front matter who want to batch-convert TOML to YAML for better editor support across tools.
- Windows users who can run the scripts through Windows Subsystem for Linux (WSL) since the repo supports macOS/Linux natively.
What can you do with Awesome Hugo?
- Upgrade a Hugo Blox site: Run singular2plural to bring content types up to v0.8.0 conventions and receive Netlify redirects in the process.
- Migrate an Academic site step-by-step: Use the page-bundles converter for v2.4.0 → v3.0.0 and the headless-bundles script for v4.1 → v4.2.
- Normalize front matter across a site: Execute the TOML-to-YAML Python converter so Markdown files open consistently in different editors.
- Test or downgrade content structure: Run the reverse page-bundles script to restore page files after a migration attempt.
How does Awesome Hugo work?
Each script runs standalone from the repository root or a site directory. Shell scripts are invoked with bash <script>.sh; the Python converter is installed via Poetry (poetry install) and run with poetry run python3 refactor_pages_convert_TOML_to_YAML.py. The README advises backing up your site, reviewing the script code, and using --dry-run whenever a script offers it.
Pros and cons
- Pros: MIT-licensed for free reuse; scripts prefer non-destructive defaults; the collection includes both Bash and Python implementations; documentation explains usage, flags, and caveats.
- Cons: Not every script has a
--dry-runoption — refactor_page_bundles_to_pages.sh lacks one, so you must manually comment outmv/rmlines to simulate a test. The README warns that the scripts can modify and delete files, so a full backup is mandatory.
Pricing
The repository is free and MIT-licensed. You can use, modify, and redistribute all scripts without charge, and contributions are welcome as long as they remain MIT-licensed.
FAQ
Is Awesome Hugo free?
Yes. The repository is licensed under MIT, so the scripts are free to use, modify, and redistribute, including in commercial projects.
Which scripts support a --dry-run?
Only singular2plural explicitly lists --dry-run support. The README suggests manually reviewing and commenting out destructive lines for the other scripts, and for refactor_page_bundles_to_pages.sh it notes there is no dry-run flag.
What are the system requirements?
macOS and Linux are supported natively. Windows users can run the scripts through Windows Subsystem for Linux (WSL). Python scripts require Python 3.8+ and use Poetry for dependency management (pyyaml, toml).
Does this work with Gatsby as well as Hugo?
The repository description states it integrates with static website generators such as Hugo and Gatsby. The concrete scripts target Hugo/Hugo Blox content structure, but the TOML-to-YAML converter could apply to any Markdown-based static site.
