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 as well.

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

1. Migrate posts
2. Migrate pages
3. Migrate tags
4. Migrate categories
5. Migrate all the URLs including media URLs correctly
6. Generate Ngninx config containing GUID -> relative URL mapping
7. Migrate iframe(s) like YouTube embeds
8. Migrate "Excerpt"
9. Migrate "catlist"
10. Set the WordPress homepage correctly
11. 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
12. Migrate favicon.ico
13. Migrate YouTube embeds, including WordPress-style plain-text URLs pasted into the content
14. Migrate Google Map embed via a custom shortcode googlemaps
15. Migrate GitHub gists
16. Migrate caption (WordPress) to figure (Hugo)
17. Migrate "Show more..." of WordPress -> Summary in Hugo
18. Support for parallax blur (similar to WordPress Advanced Backgrounds)
19. Migrate WordPress table of content -> Hugo
20. Custom font - defaults to Lexend
21. Use draft date as a fallback date for draft posts
22. Maintain the draft status for draft and pending posts
23. Migrate code blocks correctly - migrate existing code class information if available
24. Download embedded photos while maintaining relative URLs
25. Map WordPress's feed.xml to Hugo's feed.xml
26. WordPress footnotes
27. WordPress page author
28. Ability to filter by author(s), useful for WordPress multi-site migrations
29. Featured images - export featured image associations with pages and posts correctly
30. WordPress Post formats

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