# Markdown, GitLab и Docsify: как стандарт документирования

**Category:** [Основная](https://discuss.rabkesov.ru/c/main/4)
**Created:** 2025-10-24 21:46 UTC
**Views:** 20
**Replies:** 0
**URL:** https://discuss.rabkesov.ru/t/markdown-gitlab-i-docsify-kak-standart-dokumentirovaniya/257

---

## Post #1 by @ivan

![Молодой человек сидит за столом, окруженный множеством экранов с кодом, в то время как из компьютера поднимается столб дыма. (Подпись к изображению от AI)|689x394](upload://sNDcDY7czz8iFAmdWedlzyuy3Ko.jpeg)


<div data-theme-toc="true"> </div>

>- **Единый формат (Markdown)** устраняет фрагментацию.
>- **Git как основа** обеспечивает версионность, аудит и совместную работу.
>- **Docsify + GitLab** — лёгкое и быстрое решение без тяжёлых генераторов.
>- **Discourse как «песочница»** — отличная идея для коллективного уточнения идей до финальной публикации.

## Проблема: документирование в условиях многозадачности

Суета выполнения повседневных задач и частые переключения на пожары не оставлял времени на документацию. Вопрос оптимизации ее написания поднимался среди постоянных переключений между:

* CI/CD-пайплайнами
* мониторингом
* автоматизацией
* R&D
* поддержкой вышеперечисленного
* поддержкой заказчиков
* и детальным учётом времени

Возможности сосредоточиться на качественном документировании не было. А делать задачи кое-как я не умею.

Что требовалось:

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

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

>В итоге я построил **гибкую, масштабируемую и человеко-ориентированную систему документирования** , которая учитывает реалии работы инженера в условиях высокой нагрузки. Отказ от изолированных черновиков в пользу открытых обсуждений — особенно важное решение. Оно не только ускоряет доведение документа до качества, но и вовлекает команду в процесс.

## Цель: документация как код

Создавайте черновики с расширенным форматированием и работайте с документацией так же, как с программным кодом. Это даёт несколько преимуществ:

* экономия времени на форматирование и конвертацию
* автоматическая генерация онлайн-документации
* наличие офлайн-режима (благодаря кешу браузера), что особенно ценно:
  * в закрытых сетях заказчика
  * в зонах без интернета.

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


## Выбранный стек технологий

Основой стал формат **Markdown**, потому что он:

* поддерживается в GitLab, YouTrack, некоторых мессенджерах
* корректно распознаётся всеми современными LLM
* позволяет избежать проблем с версиями Word, «поехавшими» картинками и несовместимыми форматами.

Из черновика сразу можно получить:

* онлайн-версию
* строгий и красивый PDF в таком же стиле, как онлайн-версия.


## Текущая практика документирования

Сегодня документация:

* **Пишется** в формате Markdown
* **Хранится** в GitLab:
  * доступна всем сотрудникам по ролевой модели
  * поддерживает многопользовательское редактирование
* **Собирается автоматически** в онлайн-версию:
  * используется контейнер Docsify
  * обновление происходит каждую минуту
  * сайты публикуются в интернете через DNS (с именем 3 или 4 уровня для каждого проекта)
* **Экспортируется в PDF** с единым оформлением (на базе Vue.js), одинаковым для сайта и файла
* **Диаграммы** создаются в двух форматах:
  * **Draw.io** (outline, для сложных схем)
  * **Mermaid** (inline, прямо в Markdown)
* **Экспорт диаграмм**:
  * в SVG (основной формат)
  * иногда в PNG (для несовместимых платформ)
  * с включением **исходного кода** диаграммы внутрь файла.


## Модель трёх уровней документации — и её упрощение

Изначально я рассматривал три уровня документации:

1. **Черновики** — личные, быстро меняющиеся заметки.
2. **Часто изменяющаяся документация** — совместные рабочие материалы.
3. **Статическая документация** — финальные, проверенные версии.

Однако я решил:

* **отказаться от анонимности и изоляции черновиков**,
* **объединить первый и второй уровни** в общие Wiki-черновики на базе **Discourse**
* оставить **статическую документацию** в **GitLab + Docsify**.

Хотя между вторым и третьим уровнями **нет автоматической синхронизации**, я считаю такой подход жизнеспособным: он упрощает поток знаний, снижает порог входа для коллег и ускоряет переход от идеи к публикации.

## Инструменты и форматы

||||
| --- | --- | --- |
|Текст|Markdown (.md)|Основной формат написания|
|Хранение|GitLab|Версионирование, ревью, доступ по ролям|
|Онлайн-публикация|Docsify (в Docker-контейнере)|Автоматическая сборка сайта из Git|
|Черновики и обсуждения|Discourse|Коллективная проработка идей|
|Диаграммы (встроенные)|Mermaid|Блок-схемы, последовательности прямо в Markdown|
|Диаграммы (внешние)|Draw.io (.drawio → .svg)|Сложные архитектурные схемы|
|Экспорт в PDF|Docsify + единый Vue-стиль|Для офлайн-доступа и передачи заказчикам|

## Что еще

В схеме есть еще над чем поработать:

- Синхронизация между Discourse и Gitlab
- Шлифовка процесса ревью и перевода в состояние готовности к публикации финальной версии
- Соблюдение ссылочной целостности
- Автоматизация публикаций
- Механизм обратной связи по найденным несоответствиям и оповещений по исправлениям.

---


**Canonical:** https://discuss.rabkesov.ru/t/markdown-gitlab-i-docsify-kak-standart-dokumentirovaniya/257
**Original content:** https://discuss.rabkesov.ru/t/markdown-gitlab-i-docsify-kak-standart-dokumentirovaniya/257