Инструкция: Как создать документацию как код (Docs as Code)

О проекте

Этот проект создан с использованием подхода Docs as Code:

Документация пишется в Markdown.
Хранится в Git.
Генерируется в сайт через MkDocs.

Создайте репозиторий на GitHub

Откройте GitHub и войдите в аккаунт.
Нажмите зеленую кнопку "New repository".
В поле "Repository name" напишите: my-docs.
Выберите "Public" (или Private, если хотите скрыть).
Не ставьте галочку "Add a README file".
Нажмите "Create repository".

После создания GitHub покажет команды. Скопируйте ссылку вида: https://github.com/ВАШ_ЛОГИН/НАЗВАНИЕ_ПРОЕКТА.git. Используйте ее в команде git clone ниже.

Клонируйте репозиторий

Откройте PowerShell или терминал в VS Code.

Перейдите в папку, где будет проект: cd "C:\Users\ВАШ_ПОЛЬЗОВАТЕЛЬ\Documents\projects".

Склонируйте ваш репозиторий: git clone https://github.com/ВАШ_ЛОГИН/my-docs.git.

Зайдите в папку проекта: cd my-docs.

Создайте ветку для задачи

Ветка нужна, чтобы не ломать основной код.

Выполните одну из команд:

Создайте ветку: git branch task-1-add-index.
Переключитесь на ветку: git checkout task-1-add-index.
Создайте ветку одной командой, создать и переключиться: git switch -c task-1-add-index.

Создайте структуру MkDocs

Создайте папку для документации: mkdir docs.

Создайте главный файл документации: - Для Windows: type nul > docs/index.md. - Для Mac/Linux**: touch docs/index.md.

Откройте файл в VS Code: code docs/index.md.

Вставьте в code docs/index.md текст, например:

# Моя документация
Добро пожаловать в документацию проекта!

Сохраните файл (Ctrl + S).

Редактирование документа (Markdown)

Markdown — это простой язык разметки. Вот основные правила:

Что хотим сделать	Как написать	Результат
Заголовок	`# Заголовок`	Крупный текст
Подзаголовок	`## Подзаголовок`	Текст поменьше
Обычный текст	Просто пишем	Обычный текст
Жирный текст	`жирный`	жирный
Курсив	`курсив`	курсив
Список с точками	`- пункт 1`	• пункт 1
Список с цифрами	`1. пункт 1`	1. пункт 1
Ссылка	`[текст](адрес)`	текст
Картинка	`![описание](images/photo.png)` (пример)	Пример картинки

Создайте конфигурацию MkDocs

ВАЖНО: файл mkdocs.yml должен быть в корне проекта (рядом с папкой docs, а не внутри нее).

Создайте файл в корне: type nul > mkdocs.yml.
Откройте файл: code mkdocs.yml.

Вставьте в mkdocs.yml текст, например:

site_name: Моя документация
site_description: Документация проекта
docs_dir: docs

nav:
  - Главная: index.md

theme:
 name: material

Сохраните файл (Ctrl + S).

Редактирование mkdocs.yml

mkdocs.yml — это как пульт управления сайтом. Каждая строчка меняет что-то на сайте.

Строчка в файле	Что делает	Где видно на сайте
`site_name: Моя документация`	Текст в шапке	В левом верхнем углу
`site_description: ...`	Описание для поисковиков	В результатах поиска (Google, Telegram)
`nav:`	Создает меню	Слева на сайте
`theme.name: material`	Внешний вид	Весь сайт
`primary: indigo`	Цвет шапки	Верхняя полоса
`accent: deep purple`	Цвет ссылок	Все ссылки на сайте
`copyright: ...`	Текст в подвале	В самом низу страницы
`- navigation.top`	Кнопка "Наверх"	Появляется при скролле вниз

Примеры редактирования сайта

Добавление нового пункта в меню:

nav:
 - Главная: index.md
 - О проекте: about.md        - добавили эту строчку

Изменение цвета шапки:

theme:
  name: material
 palette:
   primary: red               - поменяли цвет

Какие цвета можно использовать: red, orange, yellow, green, blue, purple, pink, black, white.

Добавление иконки соцсетей внизу:

extra:
  social:
  - icon: fontawesome/brands/github
      link: https://github.com/ваш_логин
  - icon: fontawesome/brands/telegram
      link: https://t.me/ваш_ник

Главное правило YAML (Запомните!):

Только пробелы! Никаких клавиш Tab.
Отступы — 2 пробела.
После двоеточия всегда пробел.

Сохраните изменения в Git

Проверьте, какие файлы изменились: git status.

Добавьте все файлы: git add ..

Сделайте коммит (сохраняем версию): git commit -m "Добавлен index.md и mkdocs.yml".

Отправьте ветку на GitHub: git push --set-upstream origin task-1-add-index.

Проверьте, что вы в папке my-docs: pwd # должно показать ...\my-docs.

Запустите сервер через Python

Шаг 1. Установите MkDocs: pip install mkdocs mkdocs-material.
Шаг 2. Запустите сервер: mkdocs serve.
Шаг 3. Откройте в браузере: http://127.0.0.1:8000.

Чтобы остановить сервер — нажмите Ctrl + C в терминале.

Финальная структура проекта

my-docs/
├── docs/
│   ├── stylesheets/      # Папка со стилями
│   │   └── extra.css     # CSS файл
│   └── index.md          # О проекте
│   └── checklist.md      # Чеклист  
│   └── github-pr.md      # Pull Request
│   └── commands.md       # Команды Git 
│   ├── publish.md        # Публикация
│   └── mistakes.md       # Частые ошибки
├── mkdocs.yml            # Конфигурация MkDocs
├── README.md             # Описание проекта
└── LICENSE               # Лицензия