Skip to content

Blog

Hosting a Mkdocs-generated Site Using Nginx

Creating exceptional software documentation is a pivotal ingredient for product success. The NOC Team has been on a relentless journey with Project Aegeus to make our documentation truly shine. While top-notch content is essential, the delivery process plays a crucial role in shaping the user experience. In this post, we're shifting our focus to delivery, where we'll reveal some tricks that can take your documentation from good to great.

Mkdocs, especially when adorned with the stylish mkdocs-material theme, is an outstanding tool for crafting project documentation. The outcome is a directory brimming with polished HTML files and static assets. Unlike popular CMS platforms like Joomla or WordPress, your output is a self-contained directory that doesn't rely on additional runtime services or databases. This independence makes it incredibly easy to serve your documentation directly to your audience. While services like "GitHub Pages" and "Read the Docs" have their allure, there's a compelling case for hosting your documentation independently. We, for instance, rely on the rock-solid Nginx web server. In the following sections, we'll offer you a glimpse into our setup and share some simple yet highly effective tweaks to enhance performance.

Project Augeas: Unifying NOC Documentation

At NOC, we are currently revamping our documentation with "Project Augeas" to provide a better experience for our users.

The Challenge

Previously, our documentation was split into English and Russian sections, which were not consistent with each other and had excessively complex structures. Worse, a large part of the documentation was still hosted on the old Confluence system. As a result, it was hard for users to get the required information, and hard for developers to keep documentation in tune.