From Confluence to Metalsmith - A Migration Story of Nuxeo Docs

Tue 15 November 2016 By Manon Lumeau

Did you notice the big change on our documentation site last week? If not, stop whatever you are doing and take a look right now. It’s worth it!

After several months of work, we are very happy to announce that a totally revamped and brand new Nuxeo Documentation site is live!



It is not just an update of the look and feel. We changed the documentation tool itself, abandoning Confluence for a static website generated with Metalsmith. Today, we will discuss why we decided on the migration and how we improved the Metalsmith plugin ecosystem.

What is Metalsmith Static Website Generation?

The new documentation website is a set of textual content and graphical resources that goes through a set of piped transformations for generating the expected look and feel and links. Metalsmith handles that piping logic in JavaScript. It is possible to add new pipes, for instance one that will replace all {page page=’my-page’ space=’NXDOC’} by the expected link to a given page. Sources of the website are committed on GitHub.

Why We Abandoned Confluence & What We Gained With Metalsmith?

Confluence was a great tool when we started our documentation site - it was very easy to use, create, update, and maintain pages. But for several months now we have been facing some limitations and finally decided on the migration. Here’s why:

Features Added to Bare Metalsmith Generators

By reading the Metalsmith documentation, you will quickly understand that everything in Metalsmith is handled by plugins. We therefore listed all the features that we wanted to keep from Confluence and we created plugins for each of them. For example:

We also created new plugins that were not handled by Confluence. For example, for versioning we can link pages even if they have been renamed between two versions. We also implemented a documentation review process.

Most of all, this documentation website in Metalsmith leaves more room for evolution of content, layout, graphic design, and contribution.

Migration of the Content

We used the Rest API of Confluence to migrate the content and then applied some transformation to convert it to markdown. We also stripped out all useless chunks (including getting short links, history summary, last author, tags, etc.).

What’s Next?

That is just the beginning of our project! We are already working on the second version of the documentation website, with improvements on navigation, graphic, design. As Nuxeo is growing fast, the documentation needs to scale to fit the constantly evolving needs.

We hope it will make your life easier to discover Nuxeo, learn about our products, read more documentation and contribute to it. Let us know your thoughts and impression about this new website.

Lastly, if you are interested in using the Metalsmith plugins that we are writing, GitHub is your friend :) Your feedback and improvements are always welcome! There’s a lot more coming, so stay tuned for more updates!

Tagged: Documentation, Nuxeo Platform
Check out the features of our latest Nuxeo Platform Download Nuxeo