Примечание. Начинаю писать статьи, поэтому будем признательны за любые отзывы.

Введение

Управление технической документацией — это Haaaard. Все будут его писать, но никто не будет его поддерживать. Confluence, Readme, Gitbook, Read the Docs и т. д. и т. д. служат прекрасной цели, однако, если вам действительно нужна самая последняя документация для ваших систем и отделов, давайте начнем прямо сейчас!

› Если у вас нет времени читать, то вы можете просмотреть результаты [здесь]

› Или, если вы просто хотите получить исходный код с учебным пособием, посетите [github repo]

Что это такое?

docker + Mkdocs + плагины Mkdocs + draw.io + mermaid + meta

Тогда покажи мне

Установить репозиторий

git clone [email protected]:cribmove/mkdocs-example-demo.git
cd mkdocs-example.demo
cd docs
docker compose up -d

Посетите http://localhost:8124

Хорошо, но что еще?

Несколько репозиториев

Просто используя такой инструмент, как https://www.npmjs.com/package/meta, вы можете собрать множество репозиториев в центральный репозиторий = отлично подходит для наблюдения за несколькими проектами и *централизации* документации. Все, что вам нужно сделать, это подключить внешний репозиторий mkdocs.yaml, как показано ниже:

nav:
 — External Repository: ‘*include ./second-repo/mkdocs.yml’

Интеграция Draw io

Используя расширение VSCode draw.io, вы можете создавать диаграммы в редакторе кода и просматривать их в своих MKdocs!

Русалка

Если у вас есть аппетит к этому, вы можете сделать диаграмму в коде, используя синтаксис [mermaid](https://mermaid-js.github.io/mermaid/#/). Хотя существует кривая обучения, преимущества построения диаграмм рядом с вашим кодом перевешивают время обучения.

Интеграция с открытым API

Если вы придерживаетесь своей спецификации и определений API, вы можете опубликовать свои локальные определения в своей документации (опять же полезно для полирепозиториев и контрактов).

Заключение

Mkdocs не для всех, но он удовлетворяет требованиям разработчиков. Расширяемость, история git и быстрый доступ, которые дает вам Mkdocs, действительно сделают ваш опыт разработки более приятным. Вы можете не только быстро создавать, но и легко публиковать на страницах Github, в облаке и Netlify!

Попробуй!