Перейти к содержанию

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.

Проект "Авгий": Объединение документации NOC

В NOC в настоящее время проводится реформирование нашей документации в рамках "Проекта Авгий", с целью предоставить нашим пользователям более консистентную и актуальную документацию.

Проблема

Ранее наша документация была разделена на английские и русские разделы, которые не соответствовали друг другу и имели чрезмерно сложные структуры. Кроме того, большая часть документации все еще размещалась в старой системе Confluence. В результате было сложно для пользователей получить необходимую информацию, а для разработчиков - поддерживать документацию в актуальном состоянии.