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.

The following sites have migrated using wp2hugo

1. ashishb.net
2. inliniac.net
3. blog.polarweasel.org
4. open-bio.org - more details from Bastian Greshake Tzovaras
5. Virtual Andy
6. bjørn:johansen
7. xf.is
8. retro.moe
9. Marcelo Fernandez (in Spanish)
10. Mountain Water (Chinese Traditional)
11. Hit To Key
12. Chuyển địa chỉ
13. Cynarski.dev (Polish)
14. It's a Binary World 2.0
15. The Legal Beaver
16. Deuts Log
17. cloudowski
18. Population: One
19. Aurélien Pierre Engineering
20. Spinning Code
21. ITTY
22. Sean Graham
23. skyboo.net
24. Tim's tech thoughts (tsmith.co)

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.

What does wp2hugo do better than other migration tools

• wp2hugo is distributed as a single and portable binary executable, requiring no installation and no dependencies. The binary is compiled code (written in Go), which provides much better performance than scripted tools.
• It can run locally on your computer, or on a server with shell access, and process the WordPress XML export file. This makes it able to migrate very large blogs in a matter of minutes, while other migration tools (e.g., those running server-side PHP code, as WordPress plugins) may time out, overflow RAM, overload the server, and fail completely on shared hosting.
• It migrates all post metadata like GUID, custom fields, taxonomies, and more, so you retain all of your original posts' information, even hidden from the user front-end. (Posts front-matters may need some manual cleanup after migration)
• It converts a large range of native WordPress shortcodes and Gutenberg blocks to Hugo shortcodes.
• It fully imports WordPress media library (files and metadata) and fully supports WordPress galleries (legacy and Gutenberg), which makes it particularly well-suited for photo blogs.
• It supports translated pages and hierarchical pages, and custom post types.

Usage

Binary

• Install hugo, verify it is v0.146 or later with hugo version command
• 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 (using author slug)
  --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
  --content-date-folder-structure string
    organize posts/pages by publish date: flat, year, or year-month (default "flat")
  --download-media
    download media files embedded in the WordPress content
  --download-all
    download all media files from the WordPress library, whether embedded in content or not
  --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
  --custom-post-types string
    CSV list of additional WordPress custom post types to import (using type slug)

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

Documentation

More details on the documentation.

Goals of wp2hugo

Migrate post types, taxonomies, and their archive pages

1. Migrate posts
2. Migrate pages in a hierarchical way, using Hugo page bundles,
3. Migrate tags, categories and custom taxonomies for all types of posts,
4. Set the WordPress homepage correctly
5. Create WordPress author page
6. Migrate WPML translated posts, pages, and custom post types that use the URL parameter scheme (switch the WPML language URL option prior to exporting your blog content to XML),
7. Migrate any arbitrary WordPress custom post type and store them into their own /content/post-type subfolder (hierarchical custom posts are fully supported):

• Avada FAQ and Portfolios types are supported natively,
• Woocommerce products and product variations types are supported natively,
• user can specify a CSV list of arbitrary post types, using the --custom-post-types argument when calling the executable. Only post types that have a publishing status (<wp:status> in export XML) matching one of the values of native posts are supported.

Migrate comments

Provided you don't want to accept new comments, old comments are automatically migrated for all post types (posts, pages and custom). You will need to insert the provided snippet into your relevant theme's single.html template. See the documentation.

Migrate permalinks

1. Migrate all the URLs, including media URL,s 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 page excerpt
2. Migrate "Show more..." of WordPress -> Summary in Hugo
3. Migrate List Category posts(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
   3. Migrate WordPress-style plain-text YouTube embeds in the post body
   4. Migrate WP YouTube Lyte YouTube embeds
   5. Migrate Google Map embed via a custom shortcode googlemaps
   6. Migrate GitHub gists
7. Migrate WordPress shortcodes:
   1. Migrate WordPress [caption] shortcode to Hugo's {{< figure >}})
   2. Migrate WordPress [audio] shortcode)
   3. Migrate Wordpress [gallery] shortcode, including empty Gallery
8. Migrate Gutenberg blocks and features:
   1. Migrate WordPress footnotes
   2. Migrate Youtube embed Gutenberg blocks
   3. Migrate image and gallery Gutenberg blocks

More details on the documentation.

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
5. WordPress Custom fields, including PHP array deserialization for fields using them

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
4. Optionally import all media attachments from WordPress library
5. Import user-defined attachment titles into a Hugo database into /data/library.yaml

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)

Hugo Manager

This repository contains an experimental tool, hugomanager. I use this tool for the automatic generation of URLs from the title as well as for knowing which blog posts are still marked as drafts 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:
  analyze-backlinks                     Analyzes backlinks and shows good quality backlinks
  completion                            Generate the autocompletion script for the specified shell
  help                                  Help about any command
  make-absolute-internal-links-relative Converts all the absolute internal links to relative links
  move-post-next-to-attachments         Move markdown blog posts with attachments to a single directory
  shrink-audio-files                    Shrinks all audio files to be below a certain bitrate
  shrink-images                         Shrinks all images to be below a certain width/height
  sitesummary                           Print site stats (e.g. number of posts, number of drafts etc.)
  suggest-description                   Suggests description for all the posts that are missing a description in the front matter
  suggest-image-alt                     Suggests image alt text for all the images if missing
  suggest-url                           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
      --viper           use Viper for configuration (default true)

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

Feel free to send a Pull request if you migrated your website using wp2hugo

Note

1. To migrate comments, use Remark42