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 git@github.com: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

Migrate permalinks

Migrate all the URLs including media URLs correctly
Generate Nginx config containing GUID -> relative URL mapping
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
Map WordPress's RSS feed.xml to Hugo's RSS feed.xml

Migrate post content and shortcodes

Migrate post metadata and attributes

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

Migrate media attachments

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

Misc

Ability to filter posts by author(s), useful for WordPress multi-site migrations
Custom font - defaults to Lexend
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:

To migrate comments, use Remark42

ashishb/wp2hugo