The road to improving Contendo Server Documentation

Until recently, the documentation for Contendo Server lived inside our main Maven project, built with the mvn site plugin. We had experience using this plugin in past projects so it made sense to use what we know and focus on writing the documentation itself. It worked – it was easy to use and the content was displayed correctly.

Still, something felt off.

Initial Motivation

While fixing a few minor typos in the documentation, we noticed that every time we clicked a link in our Maven-generated site, the entire page reloaded. This caused a visual stutter, including on elements that didn’t change – like the left-hand menu as well as an abrupt snap-to-top if scrolled down before clicking. It was not a smooth experience. Even with the custom styling we added to modernize the default looks, the documentation site still felt outdated.

_{The Maven site: functional but outdated}

Our first thought was to check the Maven Site documentation for a solution – maybe a configuration option we didn’t know about? 

There is none.

Now, it could be done manually. For example, by writing some custom javascript to facilitate a modern single page application behaviour. If we went down this route, it would quickly become way too complicated (and likely also take way too long) when we want to focus on the content and “just” have it displayed nicely.

It was time to become our own client and find the right tool for the job.

The Goal

Let’s break it down. We wanted a documentation site that was:

• Easy to write – ideally using Markdown. We didn’t want to rewrite our existing .md files.
• Stylish with minimal effort – modern single page application feel.
• Easy and quick to use – simple tooling for building the site.
• Bonus points for a live reload capability to quickly see effects of changes.

Our Pick: MkDocs Material

After reviewing a few options, we decided on MkDocs Material. It ticked all our boxes and even came with some unexpected extras like a built-in search function.

Installing it locally was simple via brew:

brew install mkdocs-material

The MkDocs documentation suggests using pip (Python’s package installer), but we use brew for installing most things so brew it was.

We reused our existing Markdown structure – just as we wanted. Maven site uses site.xml for defining navigation and other configurations. That wasn’t usable here, but it was straightforward to rewrite to the mkdocs.yml format. We kept our custom fonts and styles, adapting them slightly to match the more modern aesthetic of Material. All in the scope of a few minutes.

We were almost there, only left to deploy it. We ran:

mkdocs build

to build the site in a new /site/ folder which we promptly rsync-ed to our server.

And done!

Or were we? We could take it a step further.

Automation with GitHub Actions

Using rsync was easy, but we can automate the build and deployment. We always push any documentation changes to our GitHub repo anyway so using GitHub Actions was the obvious next step.

In another few minutes we configured a GitHub Actions workflow that builds and deploys the documentation automatically on push to main.

Each time, the action installs MkDocs Material (from cache – no need to download it every time), builds the site, and rsyncs it to our server. Clean, reliable, and fully automated.

Of course, we added a short readme documenting how all of this works – for others in the company (and us in the future when we unavoidably forget what we did here) – changes to this are omitted from triggering a deployment.

The Result?

We now have a beautiful and automated documentation setup that will serve us and our users far better moving forward:

_{The new documentation site built with MkDocs Material}

Check out our new documentation here. What do you think?