Migrate from Confluence to Hugo

If you are paying for confluence just to host documentation with no links to JIRA whatsoever, then it might be worth thinking about moving to a Hugo powered static site.

The following is what I did. Note that the process is somewhat manual. I used the excellent "Hugo Learn Theme".

Prerequisites

1. An installation of Hugo.
2. A working pandoc installation.
3. An installation of Confluence to Markdown converter.
4. An HTML export from the Confluence space. This is described here.
5. Git of course.

Create your documentation site.

Follow hugo's documentation to start a new site. Briefly,

$ hugo new site yoursite 
$ cd yoursite
$ git init
$ git submodule add https://github.com/matcornic/hugo-theme-learn.git themes/hugo-theme-learn
$ echo 'theme = "hugo-theme-learn"' >> config.toml

Note that I added the theme as a git submodule rather than downloading it manually. This will let me update the theme independent of my sources.

If at this point you push this to some git hosting service and someone decides to clone it, they'd probably have to do the following.

$ git clone yoursite
$ cd yoursite
$ git submodule init
$ git submodule update

Manual part

The confluence to markdown converter is straightforward to use. It will produce the markdown in a separate folder, leaving the original intact.

Now do the following.

1. Get the static contents into your site's static folder.

Copy the "attachments" and "images" folders from the markdown output folder to the "static" folder of your site.

$ls static/
attachments     images

2. Create the page structure as per your confluence

The reason I chose learn theme was that it has the notion of "chapters" and can be nested as much as you need.

Start off the top level topics in your Confluence as "chapters"

Chapters can be created using archetypes provided by the theme.

For example,

$hugo new --kind chapter engineering-practices/_index.md

would create content/engineering-practices/_index.md and peg it as a top level topic. This will show up as the menu entry in the sidebar.

Make sure that _index.md has the following attributes in its front matter.

• chapter : true
• weight : (a number)

The "weight" attribute decides the ordering of the side menu.

3. Create pages as per confluence.

This is the manual part #1 . I had the original HTML export opened in a browser tab while I recreated the structure.

Create the pages like so:

$hugo new  <chaptername>/<subtopic>.md

4. Copy paste the markdown content.

This is manual part #2. It is mostly a straight copy paste. The part you'd have to pay attention to is the links in the document.

Mostly, I only needed to change them from "attachments/path-to-file" to "/attachements/path-to-file". The difference is that single forward-slash character.

Also, the "weight" attributes count here too. You can control the ordering using weight.

Miscallaneous stuff.

The theme has a blue, green and red variant. Use the 'params' section config.toml to make a choice.

[params]
  # Change default color scheme with a variant one. Can be "red", "blue", "green".
  themeVariant = "blue"

The logo can be changed to whatever you want using "layouts/partials/logo.html" file. Create this file and put either an image tag inside it, or an SVG. I used an SVG