MkDocs - это быстрый и простой генератор статических сайтов, предназначенный для создания проектной документации.

Столкнулся с проблемой - описал ее.

После решения различных проблем и прочего с серверами и linux системами делал много всяких заметок о том как именно решить ту или иную задачу. Ведь со временем все забывается, а гуглить опять часами или даже днями не хочется. И вот накопилось достаточно большое количество всяких записей.

Сначала все это было в виде текстовых файлов, а потом переросло в вики сайт на движке pmwiki, который работал на небольшом домашнем сервере. Следующим этапом было перевести все записи в маркдаун формат и хранить все это в приватном репозитории. Так легче поддерживать записи и упрощает процесс развертывания.

Для меня хранение записей в формате Markdown имеет ряд преимуществ:

• Гибкость. Нет привязок к конкретным системам типа Evernote или Notion.
• Удобное форматирование.
• Красивое отображение.

Ну и в идеале что бы из всего этого генерился простенький статический сайт с возможностью поиска по записям. И в результате гугления, чтения статей и просмотов видосов на ютубе было найдено решение. Сначала это был gitbook, но в последствии перешел на mkdocs. Очень порадовала его скорость работы и livereload(обновление в браузере при изменении файлов).

И вот, эта инструкция о том как создать простой сайт для отображения различной документации в формате простых .md файлов.

Для начала устанавливаем пакет mkdocs.

pip install mkdocs

Команды mkdocs

• mkdocs new [dir-name] - Создать новый проект.
• mkdocs serve - Запустить live-reloading сервер.
• mkdocs build - Сгенерировать статический сайт на основе наших .md файлов.
• mkdocs -h - Показать справку по командам.

Создаем новый проект

mkdocs new my-project
cd my-project

Здесь видим структуру нашего проекта.

my-project
├── docs
│   └── index.md
└── mkdocs.yml

mkdocs.yml - файл конфигурации нашего проекта
docs - папка в которой будет находится наша документация в виде файлов формата .md, разсортированных при необходимости по каталогам.

mkdocs имеет встроенный dev-server для просмотра нашей документации. Для запуска необходимо из директории нашего проекта, где лежит файл mkdocs.yml, ввести команду:

mkdocs serve

$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.04 seconds
INFO     -  [10:18:31] Serving on http://127.0.0.1:8000/
INFO     -  [10:18:38] Browser connected: http://127.0.0.1:8000/

И переходим по указанному адресу.

dev-server также поддерживает автообновление после правки .md файлов. Можем открыть docs/index.md и попробовать что то в нем написать в формате маркдаун.

Настройка конфигурационного файла

Открываем в редакторе mkdocs.yml.

• site_name - Для изменения имени сайта с проектом
• site_url - соответственно URL сайта
• nav - блок навигации
• theme - тема оформления

site_name: My Docs
site_url: https://example.com/

nav:
        - Home: index.md
        - About: about.md

theme: readthedoc

Добавление новых страниц

Для добавления новых записей достаточно их создать в папке docs и добавить в секцию nav в файле mkdocs.yml. При необходимости сортируем все по папкам.

У меня это выглядит вот так: