Привет!
Что ж, мы отлично поработали на этой неделе: создали свой репозиторий, научились работать с гитом, написали первый документ в маркдауне.

Сейчас наш проект состоит из одного файла index.md
Мы можем добавить ещё несколько документов (сколь угодно много файлов name.md), и да, мы обеспечили надёжное хранение наших данных с возможностью отслеживать версии и контролировать вносимые изменения. Но как же нам пользоваться написанной документацией? Конечно, мы можем открывать превью любого файла прямо в гитхабе, только это неудобно и непрактично. Нам нужно придумать, как сформировать из имеющихся исходников структурированную и дружелюбную систему документации.
На помощь приходят статические генераторы. SSG (static site generators) — это программы, которые конвертируют размеченные файлы в html-страницы и собирают из них статический веб-сайт, который можно опубликовать на любом хостинге в интернете. Статический сайт — это отличный вариант для представления документации. Мы можем настроить процесс таким образом, чтобы при каждом обновлении ветки main в нашем репозитории запускалась конвертация markdown-файлов в html и пересобирался сайт с документацией.

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

В рамках нашего курса по docs-as-code мы будем использовать генератор MkDocs, а точнее, тему material генератора MkDocs.

Уже в следующем посте мы установим генератор и попробуем собрать локальную версию нашей доки. А пока немного предлагаю немного насладиться сентябрьской субботой (надеюсь, она у вас солнечная) и отдохнуть от рабочей недели 🍂

P.S. Давайте соберём 40 птичек в реакциях к этому посту, и я расскажу увлекательную историю про мое первое знакомство со статическими генераторами. Старый добрый интерактив 🕊

#практика #docsascode