/wp2hugo

The best WordPress to Hugo migrator (written in Go)

Primary LanguageGoOtherNOASSERTION

WordPress to Hugo Static site migrator

Build Go

Lint Go Lint Markdown Validate Go code formatting

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.

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

Now, run this

$ 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 more more media download fails
  -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 the 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

Packaging status

Goals of wp2hugo

  1. Migrate posts
  2. Migrate pages
  3. Migrate tags
  4. Migrate categories
  5. Migrate all the URL including media URLs correctly
  6. Migrate iframe(s) like YouTube embeds
  7. Migrate "Excerpt"
  8. Migrate "catlist"
  9. Set WordPress homepage correctly
  10. Migrate RSS feed with existing UUIDs, so that entries appear the same - this is really important for anyone with a significant feed following, see more details of a failed migration
  11. favicon.ico
  12. YouTube embeds
  13. Google Map embed via a custom short code googlemaps
  14. Migrate caption (WordPress) to figure (Hugo)
  15. Migrate "Show more..." of WordPress -> Summary in Hugo
  16. Support for parallax blur (similar to WordPress Advanced Backgrounds)
  17. Migrate WordPress table of content -> Hugo
  18. Custom font - defaults to Lexend
  19. Use draft date as a fallback date for draft posts
  20. Maintain the draft status for draft and pending posts
  21. Migrate code blocks correctly - migrate existing code class information if available
  22. Download embedded photos while maintaining relative URLs
  23. Map WordPress's feed.xml to Hugo's feed.xml
  24. WordPress footnotes
  25. WordPress page author
  26. Ability to filter by author(s), useful for WordPress multi-site migrations
  27. Featured images - I tried this WordPress plugin but featured images are simply not exported

Why existing tools don't work

  • Jekyll Exporter always times out for me
  • Various options can be seen here that are partially good.
    1. Export via https://<website>/wp-admin/export.php
    2. The problem is that there is no good tool to perform a proper import into Hugo

Note:

  1. To migrate comments, use Remark42