Документация в Markdown без Word

Документацию в Markdown ведут как набор файлов .md: заголовки #, списки, ссылки, картинки рядом в docs/. Word оставляют договорам и правкам юриста. Руководство пользователя, описание API и внутренняя база знаний живут в Git: правка одной строки видна в диффе, конфликт правите текстом, а не бинарником. Среду вроде MkDocs вы ставите один раз. Она читает папку, рисует меню и поиск. Это среда сборки, не бренд и не единственный способ публикации. Таблицу из Excel не набирайте вертикальными чертами: загрузите лист на XLSX → Markdown. Гостю без репозитория отдайте HTML или PDF через конвертер Markdown. README в корне репозитория оформляйте отдельно: как оформить README. Дальше: чем Word мешает команде, как разложить файлы, что делает MkDocs, как проверить превью и куда деть PDF.

Почему документацию вытаскивают из Word

Коллега правит главу «Установка» в .docx на диске. Второй коллега правит ту же главу в почте. Третий собирает PDF «на вчера». Вы склеиваете версии руками и теряете абзац про переменные окружения. Документация в Markdown этот сценарий режет: один файл в Git, одна история правок, сборка сайта или PDF по кнопке.

Word удобен, когда документ один и его читают как письмо: договор, акт, служебная записка. Руководство на 40 страниц с оглавлением, скриншотами и перекрёстными ссылками в Word держится, пока автор один. Как только пишут двое, бинарник .docx даёт конфликт «возьми целиком мой файл или целиком его». Текстовый .md показывает, какая строка изменилась.

Запрос «документация в markdown» чаще про этот выбор среды, а не про синтаксис звёздочек. Человек уже знает, что GitHub рисует превью из .md. Не хватает ответа, куда класть главы, чем собирать сайт и как отдать PDF заказчику, у которого нет VS Code.

Типичный провал: команда копирует главы в Confluence «для красоты» и забывает исходник. Через полгода Confluence живёт своей жизнью, репозиторий отстаёт, а релиз выходит с инструкцией к прошлой версии. Держите канон в .md. Вики, если нужна, собирайте из тех же файлов или оставляйте ссылку на собранный сайт.

Проверьте себя: откройте последнюю правку документации и спросите, кто её утвердил. Если ответа нет в Git и нет в письме с вложением «финал_3_точно.docx», канона нет. Сначала решите, какой файл источник, потом выбирайте MkDocs или другой сборщик.

Как устроена документация в Markdown

Рабочая схема для большинства продуктов: в корне репозитория короткий README.md, рядом каталог docs/ с главами. Каждая глава: один файл, один h1 внутри или заголовок из имени файла, как велит ваш сборщик. Картинки лежат в docs/assets/ или docs/images/. Ссылки между главами относительные: ../api/auth.md, не C:\Users\....

Имя файла латиницей и с дефисами: install.md, api-auth.md. Пробелы и кириллица в пути ломают сборку на CI и ссылки в Windows. Язык глав совпадает с языком аудитории. Русский продукт для русскоязычной поддержки пишите по-русски. Английский том имеет смысл, если поддержка отвечает на английском.

Ниже два слоя, которые путают чаще всего.

Канон в Git и копия для гостя

Канон: файлы .md в ветке, которую вы мержите в основную. Правка без пулла в эту ветку для продукта не существует. Копия для гостя: собранный HTML-сайт, PDF, иногда .docx. Копию вы пересобираете из канона. Править HTML руками после сборки нельзя: следующая сборка затрёт правку.

Заказчику без доступа к репозиторию отдайте HTML или PDF. Загрузите главу или весь том на конвертер Markdown и скачайте нужный формат. Файл на стороне Тулси нужен только для ответа. Если глав много и вы уже живёте в MkDocs, отдайте собранный site/ или выгрузку PDF из своей среды. Конвертер на сайте закрывает разовую главу, письмо и человека без Python.

Как открыть .md у себя на машине, если сборщика нет: чем открыть файл .md. Для проверки одной главы хватит превью в редакторе. Для проверки меню и поиска нужна сборка.

Оглавление, якоря и картинки

Оглавление в Markdown это либо список ссылок в index.md, либо меню, которое сборщик строит из mkdocs.yml или аналога. Ручной список ссылок дублирует меню и устаревает. Если вы уже на MkDocs, оглавление держите в конфиге. Если сборщика нет, один index.md со ссылками на главы лучше, чем десять файлов без входа.

Якоря: заголовок ## Ошибки 401 даёт якорь в большинстве сред. Ссылка с другой главы: [ошибка 401](errors.md#oshibki-401) или как нормализует ваш сборщик. Пробелы в заголовке превращаются в дефисы. Смените формулировку заголовка, проверьте все ссылки на него. Сломанный якорь в документации выглядит как «страница открылась не там».

Картинка: относительный путь, разумный вес, подпись в тексте рядом, не только в alt. PNG на 8 МБ в главе «Быстрый старт» тормозит и сайт, и Git. Скриншот обрежьте до окна, которое описываете. Если таблица жила в Excel, сначала сетка в Markdown, потом уже скриншот листа как запасной вид.

MkDocs как среда сборки

Запрос «mkdocs» в поиске часто ведёт на сайт проекта и тему Material. Для статьи Тулси это шум бренда. Вам нужна среда: программа читает docs/ и конфиг, отдаёт статический HTML. MkDocs одна из таких сред. Material это тема оформления поверх MkDocs: шрифты, поиск, вкладки, тёмная схема. Тема не заменяет файлы .md и не пишет главы за вас.

Вы ставите MkDocs локально или в CI, один раз описываете nav в mkdocs.yml, кладёте главы в docs/. Команда mkdocs serve поднимает превью на машине. Команда mkdocs build кладёт сайт в site/. Хостинг: GitHub Pages, свой nginx, каталог на внутреннем диске. Выбор хостинга вторичен. Сначала живые .md и меню, которое совпадает с тем, как люди ищут главу.

Полный учебник установки, Docker-образы и список плагинов Material в эту статью не входят. Документация проекта MkDocs это закрывает. Здесь задача другая: понять, зачем среда вообще, и не путать её с каноном. Канон это текст. Среда это сборка. Сменили MkDocs на Sphinx, Docusaurus или Hugo: файлы .md уезжают с небольшими правками фронтматтера. Сменили Word на Google Docs: вы снова в бинарнике и в чужой истории версий.

Тема Material всплывает в запросе «mkdocs material», потому что скриншоты в интернете чаще с ней. Для команды из трёх человек хватит темы по умолчанию. Material имеет смысл, когда нужен поиск из коробки и привычный вид «как у чужих docs». Не начинайте проект с выбора темы. Начните с двух глав и рабочего nav.

Секреты, ключи API и дампы логов в docs/ не кладите. Сборка уедет на публичный хостинг вместе с главой. Имя переменной и ссылка на .env.example достаточны. Внутренние runbook с паролями держите в закрытом репозитории или в другом контуре.

Как перенести черновик из Word и Excel

Черновик уже есть: 20 страниц .docx, три листа Excel со сводом ошибок, папка скриншотов. Цель: канон в .md, таблицы как сетка |, картинки по относительным путям. Ручной набор 40 строк таблицы вертикальными чертами даёт сбой в числе столбцов. Сначала файлы, потом украшение темы.

Вынесите из Word структуру: какие разделы станут файлами. Один файл на тему, которую человек ищет целиком: «Установка», «Авторизация», «Коды ошибок». Кусок «про всё сразу» на 15 экранов в одном index.md снова превращает docs в непроходимый том.

Текст из Word копируйте в редактор как обычный текст, затем разметьте заголовки # и списки. Сноски Word, автонумерация и внедрённые объекты Excel в .md не переезжают. Таблицу сохраните отдельно в .xlsx.

Таблица из Excel в главу

Сетка тарифов, матрица «платформа × функция», список кодов ответа: это читают глазами по столбцам. Абзац «поддерживается / не поддерживается» пропускают. Markdown-таблица в превью GitHub и в MkDocs читается, если столбцов мало и заголовки короткие.

Загрузите лист на XLSX → Markdown и вставьте сетку в главу. Узкая таблица: 3-6 столбцов. Широкий прайс на 15 колонок на телефоне уедет в горизонтальный скролл. Тогда в главе оставьте 4 главных столбца и дайте ссылку на полный лист или на отдельную страницу.

Если сетка «поехала» после вставки, сначала сверьте число разделителей | в каждой строке. Разбор типичных поломок: почему ломаются таблицы в Markdown. Повторная конвертация без правки исходника Excel ту же ошибку воспроизведёт.

Глава для человека без репозитория

Поддержка и заказчик часто не клонируют Git. Им нужна страница или PDF. Соберите сайт MkDocs и отдайте ссылку. Если сайта ещё нет, одну главу прогоните через Markdown → HTML или через конвертер Markdown, если нужен PDF или Word.

Проверьте скачанный HTML в браузере: заголовки, список, таблица, картинки. Относительные пути к картинкам в одиноком файле без папки assets/ дадут пустые рамки. Либо вложите картинки в ZIP вместе с HTML, либо соберите полный site/ у себя.

Не обещайте, что HTML с конвертера заменит MkDocs навсегда. Конвертер закрывает выдачу. Среда закрывает меню, поиск и ежедневные правки команды.

Как проверить сборку и что ломается

Перед публикацией откройте превью так, как его откроет коллега: mkdocs serve или собранный site/index.html в браузере. Просмотр сырого .md в редакторе не ловит битые ссылки между главами и картинки с неверным путём.

Пройдите меню сверху вниз. Каждый пункт должен открывать ту главу, которую вы назвали в nav. Пункт «API» на файл install.md путает сильнее, чем отсутствие пункта. Поиск по слову из заголовка главы должен находить страницу. Если поиск пустой, вы смотрите не ту сборку или тема без индекса.

Битая картинка: путь от файла главы, не от корня репозитория. Файл docs/guide/install.md и картинка docs/assets/cli.png ссылаются как ../assets/cli.png. Ссылка /assets/cli.png сработает на одном хостинге и умрёт на другом.

Якорь после смены заголовка: откройте старую ссылку из чата поддержки. Если страница прыгает в начало, поправьте ссылки или оставьте скрытый якорь, если сборщик это умеет. Не копируйте URL из превью редактора: у GitHub, у MkDocs и у VS Code якоря нормализуются по-разному.

Конфликт в Git на .md правите как текст. Конфликт на site/ не должен возникать: каталог сборки в .gitignore. Если кто-то закоммитил site/, удалите его из индекса и оставьте сборку CI.

Версия продукта в шапке документации должна совпадать с тегом релиза, который вы описываете. Глава «новое в 3.2» при установленном 3.1 роняет доверие быстрее опечатки. Держите номер версии в одном месте конфига или во фронтматтере, не копируйте его в десять абзацев руками.

Смежные задачи: README, HTML, таблица

README в корне отвечает на вопрос «что это и как запустить за минуту». Длинные главы, коды ошибок и скриншоты мастера живут в docs/. Путать эти два слоя вредно: README раздувается, а гость не находит установку. Порядок блоков README: как оформить README. Запрос «как написать readme» закрывайте той статьёй, не копируйте шапку репозитория в каждую главу MkDocs.

Выдача HTML без своей среды: Markdown → HTML. Выдача PDF или Word из той же главы: конвертер Markdown. Таблица из Excel: XLSX → Markdown. Файл .md на компьютере без превью: чем открыть файл .md.

Confluence как источник канона в эту схему не входит. Выгрузка вики в .md и обратный залив в Confluence это отдельный контур с потерей макросов. Если канон уже в Git, оставьте Confluence витриной со ссылкой на собранный сайт.

Частые вопросы

Что такое MkDocs?

MkDocs это программа, которая читает папку с файлами Markdown и конфиг меню, затем собирает статический HTML-сайт документации. Вы правите .md, запускаете превью или сборку, выкладываете каталог site/ на хостинг. Сама программа не хранит канон: канон это ваши файлы в Git. Тема оформления, в том числе Material, меняет вид сайта, не структуру глав.

Чем MkDocs Material отличается от MkDocs?

Material это тема для MkDocs: внешний вид, поиск, некоторые блоки вроде вкладок и подсказок. Без темы MkDocs тоже собирает сайт, только скромнее. Запрос «mkdocs material» обычно про скриншоты чужих docs, не про отдельный язык разметки. Ставить тему имеет смысл, когда базового вида не хватает. Главы .md пишете одинаково в обоих случаях.

Можно ли вести документацию в Markdown без MkDocs?

Да. Канон это файлы .md в Git. Превью даёт редактор, GitHub, GitLab. Сборку сайта можете отложить, пока глав две и команда читает репозиторий. MkDocs нужен, когда появляется меню, поиск и гость без Git. До среды одну главу отдайте HTML с Markdown → HTML.

Чем документация в Markdown лучше Word?

Правка видна по строкам в Git. Конфликт двух авторов вы правите в тексте, не выбираете «чей файл целиком». Сайт, PDF и HTML собираете из тех же файлов. Word выигрывает в сценарии одного договора с рецензиями юриста в режиме исправлений. Руководство продукта на десятки глав в .docx разъезжается по почте.

Куда класть файлы: README или docs?

В корне README.md: что за продукт, как запустить, ссылка на полную документацию. В docs/: главы, которые не нужны в первые 30 секунд. Дублировать установку в обоих местах можно коротко в README и подробно в docs/install.md. Два полных руководства в двух местах разъедутся после первого релиза.

Как вставить таблицу из Excel в документацию Markdown?

Сохраните лист .xlsx, загрузите на XLSX → Markdown, вставьте сетку в главу. Держите 3-6 столбцов и короткие заголовки. Если таблица поедет, сверьте число | и читайте почему ломаются таблицы в Markdown. Широкий прайс лучше разрезать или вынести из узкой колонки сайта.

Как отдать документацию заказчику без Git?

Соберите сайт MkDocs и пришлите ссылку либо архив site/. Одну главу загрузите на конвертер Markdown и скачайте HTML, PDF или Word. Проверьте картинки: одинокий HTML без папки ресурсов покажет пустые места. Для постоянного гостя выгоднее постоянный URL собранного сайта, чем письмо с вложением каждую неделю.

Почему после сборки MkDocs ломаются ссылки и картинки?

Чаще всего путь считают от корня репозитория, а сборщик считает от файла главы. Второй источник: пункт меню в mkdocs.yml смотрит на старое имя файла после переименования. Третий: якорь после смены текста заголовка. Откройте превью в браузере и кликните каждую ссылку из оглавления. Сырой .md в редакторе эти ошибки не показывает.

Нужен ли Docker, чтобы вести документацию в Markdown?

Нет. MkDocs ставится в обычное окружение Python на машине автора или в CI. Docker имеет смысл, если команда хочет одинаковую версию сборщика без «у меня собралось». Документация в Markdown не требует контейнера. Начинать проект с образа и плагинов Material до первой главы обычно тормозит появление канона.

Как написать README, если уже есть docs?

README остаётся картой на 30 секунд: имя, одна фраза, быстрый старт, ссылка в docs/. Не копируйте туда том из MkDocs. Порядок блоков и таблицы в README разобраны отдельно: как оформить README. Если гость после README не понимает, куда идти за кодами ошибок, в шапке не хватает одной ссылки на главу, а не ещё десяти абзацев.

Соседние разборы: как оформить README, чем открыть файл .md, почему ломаются таблицы в Markdown. Для выдачи главы без своей среды откройте конвертер Markdown.