WordPress to Hugo Static site migrator

This is the best migrator for migrating WordPress export to Hugo. It handles several weird edge cases that I encountered while trying to migrate my personal website to Hugo-based site.

While this primarily targets Hugo-based code generation, one can use it to convert WordPress blogs to Markdown-based files that can be used with other systems for example Mkdocs or Jekyll.

Commercial usage

I want this project to be as widely accessible as possible, while still funding the development costs. This project is completely free for non-commercial and personal usage. Commercial usage is restricted via a license. Feel free to contact me if you want to license this commercially.

Usage

Binary

• Download the wp2hugo tool from releases
• Export your WordPress website via Tools -> Export in your admin dashboard
• Let's say the downloaded file is wordpress-export.xml generate the website using $ wp2hugo --source wordpress-export.xml --download-media

$ wp2hugo
Usage of wp2hugo:
 -authors string
   CSV list of author name(s), if provided, only posts by these authors will be processed
  -color-log-output
   enable colored log output, set false to structured JSON log (default true)
  -continue-on-media-download-error
   continue processing even if one or more media downloads fail
  -download-media
   download media files embedded in the WordPress content
  -font string
   custom font for the output website (default "Lexend")
  -media-cache-dir string
   dir path to cache the downloaded media files (default "/tmp/wp2hugo-cache")
  -output string
   dir path to write the Hugo-generated data to (default "/tmp")
  -source string
   file path to the source WordPress XML file

Build from source

$ git clone [email protected]:ashishb/wp2hugo.git
$ cd wp2hugo/src/wp2hugo
$ make build_prod
# `./bin/wp2hugo` will contain the binary and you can use it as `$ ./bin/wp2hugo --source wordpress-export.xml --download-media`

Installation via Package Managers

Goals of wp2hugo

Migrate post types, taxonomies and their archive pages

1. Migrate posts
2. Migrate pages
3. Migrate tags
4. Migrate categories
5. Migrate Avada custom post types (FAQ, Portfolios)
6. Set the WordPress homepage correctly
7. Create WordPress author page

Migrate permalinks

1. Migrate all the URLs including media URLs correctly
2. Generate Nginx config containing GUID -> relative URL mapping
3. Migrate the RSS feed with existing UUIDs, so that entries appear the same - this is important for anyone with a significant feed following, see more details of a failed migration
4. Map WordPress's RSS feed.xml to Hugo's RSS feed.xml

Migrate post content and shortcodes

1. Migrate "Excerpt"
2. Migrate "Show more..." of WordPress -> Summary in Hugo
3. Migrate "catlist"
4. Migrate WordPress table of content -> Hugo
5. Migrate code blocks correctly - migrate existing code class information if available
6. Migrate embeds:
   1. Migrate iframe(s) like YouTube embeds
   2. Migrate YouTube embeds, including WordPress-style plain-text URLs in the post body
   3. Migrate Google Map embed via a custom shortcode googlemaps
   4. Migrate GitHub gists
7. Migrate WordPress shortcodes:
   1. Migrate [caption] shortcode (WordPress) to {{< figure >}} (Hugo) (reference)
   2. Migrate [audio] shortcode (reference)
8. Migrate Gutenberg blocks and features:
   1. Migrate WordPress footnotes
   2. Migrate WordPress gallery

Migrate post metadata and attributes

1. Maintain the draft status for draft and pending posts
2. Use draft date as a fallback date for draft posts
3. Featured images - export featured image associations with pages and posts correctly
4. WordPress Post formats

Migrate media attachments

1. Migrate favicon.ico
2. Migrate wp-content/uploads images embedded in pages to Hugo static files while maintaining relative URLs
3. Migrate external images (on different hosts) to Hugo static files

Misc

1. Ability to filter posts by author(s), useful for WordPress multi-site migrations
2. Custom font - defaults to Lexend
3. Support for parallax blur backgrounds (similar to WordPress Advanced Backgrounds)

Why existing tools don't work

Existing tools do a half-baked job of migrating content. They rarely migrate the metadata like GUID, YouTube embeds, Google Map embeds, and code embeds properly.

Hugo Manager

This repository contains an experimental tool hugomanager. I use this tool for the automatic generation of URLs from title as well as for knowing which blog posts are still marked draft or which ones are scheduled to be published soon.

You can build that via

src/wp2hugo $ make build_hugo_manager
...

src/wp2hugo $ ./bin/hugomanager
A tool for managing Hugo sites e.g. adding URL suggestions, generating site status summary etc.

Usage:
  hugomanager [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  sitesummary Print site stats (e.g. number of posts, number of drafts etc.)
  urlsuggest  Suggests URLs for all the pending/future posts that are missing a URL
  version     Print the version number of HugoManager

Flags:
  -a, --author string    author name for copyright attribution (default "YOUR NAME")
      --config string    config file (default is $HOME/.cobra.yaml)
  -h, --help             help for hugomanager
  -l, --license string   name of license for the project
      --viper            use Viper for configuration (default true)

Use "hugomanager [command] --help" for more information about a command.

Note:

1. To migrate comments, use Remark42