Conversion tools from Wordpress to Hugo

NGINX-logo

Converting the Wordpress content to Hugo, could be a simple task, if there were good Wordpress to Hugo converting tools available. I tested 3 tools, only the first and the forth one is made for Hugo:

  1. Wordpress Plugin->Wordpress To Hugo Exporter
  2. WP2md
  3. ExitWP for Jekyll
  4. ExitWP for Hugo My own conversion tool.

The tested conversion tools

Before I start, I want to say anything about the Wordpress conversion. My blog contains content from 2006, which was written in Drupal, later I converted it into Wordpress and now to Hugo. So maybe Wordpress content is a little bit more complex to convert than for your situation. I also have 289 posts/pages to convert, so do it by hand is not an option. That’s why I invested the time to have my own conversion tool. Also want to say that this guys did a good job to write a conversion tool, but maybe the result is not exactly what you want.

Wordpress To Hugo Exporter

To install the Wordpress Plugin->Wordpress To Hugo Exporter, you have to do the following steps:

  1. Download a zip file with the plugin here
  2. Create the directory wordpress-to-hugo-exporter in the Wordpress plugin directory
  3. unzip the file there and set the ownership and dir/file rights of these files
  4. Make sure extension=zip.so line is uncommented in your php.ini
  5. Activate the plugin in Wordpress dashboard
  6. Select menu in Wordpress: Tools->Export to Hugo and the export zip will be downloaded

The result

The export zip file is simple to use, it contains the complete directory structure what you need for Hugo. Also the export looks pretty much the same in Hugo as you had in Wordpress.

What I did not like is a LOT of HTML code in the markdown files. If this is not a problem for you, it is a good tool. If you would like clean markdown files as a result, you have to go to further.

WP2md

WP2md is a tool in Python. Not an Wordpress to Hugo converter, it converts only to markdown. You can install it by using:

$ pip install git+https://github.com/dreikanter/wp2md

It will also install the python packages: html2text and python-markdown

To use the WP2md tool, you need to:

  1. Go in Wordpress dashboard to menu: Tools->Export, and download the XML with all content
  2. Run:

    $ mkdir ~/wp2md
    $ wp2md -d ~/wp2md wordpress-export.xml
    
  3. The “~/wp2md” will contain an output directory with the markdown export results.

The result

The markdown files are pretty clean, not much HTML code in it. But it does not have a correct YAML or TOML header, which is used by Hugo. There were also other strange things like missing bullet lists and some paragraphs. So I didn’t researched it further. But the code of the tool is nicely written and has a good structure. A good base for develop your own Wordpress to Hugo convert tool.

ExitWP for Jekyll

This ExitWP for Jekyll conversion tool is specially made for Jekyll. Jekyll and Hugo do have some differences in the markdown header. But with some search and replace tooling it’s possible to adapt the markdown files for Hugo.

  1. Download the zip file or clone using git clone https://github.com/thomasf/exitwp.git

    $ cd ~
    $ unzip exitwp-master.zip
    $ mv exitwp-master exitwp-for-jekyll
    $ cd exitwp-for-jekyll
    
  2. Export one or more wordpress blogs using the wordpress exporter under Tools->Export in wordpress admin.

  3. Put all wordpress xml files in the wordpress-xml directory

  4. Run the converter by typing python exitwp.py in the console from the directory of the unzipped archive

    $ python exitwp.py
    
  5. You should now have all the blogs converted into separate directories under the build directory

Now we can remove some Jekyll parts out of the header

$ perl -i.BAK -ne "print unless /^(author|comments|layout|wordpress_id): /" *.markdown

And rename the .markdown files into the .md extension:

$ rename 's/\.markdown$/\.md/' *.markdown

The result

With the extra last 2 commands it is usable by Hugo. The markdown output is pretty clean, but there are some things not correct. For example a bullet list has some 1 or 2 linefeeds between each row. And in the <pre> blocks are italics and bold marks, which will not be translated by Hugo to italics ‘_’ and bold ‘**‘. Hugo will show these codes. And the markdown contains a lot of extra line feeds like 5 or 6 behind each-other. This makes it a little bit messy. But this tool is very close of what I want. I decided to look at the code and try to fix things. The result is in the next step.

Final solution: ExitWP for Hugo

This ExitWP for Hugo conversion tool is the ExitWP tool for Jekyll from the previous step, but I changed the code for using with Hugo.

  1. Download or clone using git clone https://github.com/thomasf/exitwp.git

    $ cd ~
    $ unzip exitwp-for-hugo-master.zip
    $ mv exitwp-for-hugo-master exitwp-for-hugo
    $ cd exitwp-for-hugo
    
  2. Export one or more wordpress blogs using the wordpress exporter under Tools->Export in wordpress admin.

  3. Put all wordpress xml files in the wordpress-xml directory

  4. Run the converter by typing python exitwp.py in the console from the directory of the unzipped archive

    $ python exitwp.py
    
  5. You should now have all the blogs converted into separate directories under the build directory

Rename the .markdown files into the .md extension:

$ rename 's/\.markdown$/\.md/' *.markdown

The result

This ExitWP for Hugo conversion tool is not perfect, but until now the best solution for me. I’ve very clean markdown files, not much HTML code in it. Only tables are not converted, these are still in HTML. I converted some by hand, but the rest is ok for me.

With sed it is possible to search and replace in all files, like in <pre> blocks before terminal commands I wrote always ‘#’ but this can cause some problems in Hugo, because it’s a <H1> mark. I changed it into ‘$’ with this command, but be careful with these kind of commands and make a backup before you start:

$ sed 's/^    # /    $ /' *.md

Also in editors like Notepad++ is a good search and replace tool to optimize the result.

At this moment the content in the markdown files is ready to use. How to do this is described next part of this guide


The next posts are guiding you through how to use Hugo:

  1. Why changing from WordPress to Hugo
  2. Conversion tools from Wordpress to Hugo
  3. Migrating from Wordpress to Hugo