Merge pull request #1 from dementev-dev/feature/mkdocs-site

feat(site): MkDocs Material сайт с деплоем на GitHub Pages
2026-03-27 23:07:09 +03:00
parent 2967664e43 a1f2643841
commit 537e77eba6
10 changed files with 824 additions and 104 deletions
@@ -0,0 +1,43 @@
 name: Deploy MkDocs to GitHub Pages
 on:
  push:
    branches: [main]
  workflow_dispatch:
 permissions:
  contents: read
  pages: write
  id-token: write
 concurrency:
  group: "pages"
  cancel-in-progress: false
 jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"
      - run: pip install mkdocs-material==9.6.14 mkdocs-same-dir==0.1.3
      - run: mkdocs build --strict
      - uses: actions/upload-pages-artifact@v3
        with:
          path: site/
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4
@@ -1,3 +1,5 @@
 .env
 .idea
 .internal/
 site/
 tmp
@@ -1,9 +1,12 @@
 # Repository Guidelines
 ## Project Structure & Module Organization
- Root `README.md` describes the learning roadmap (RU).
+- Root `README.md` describes the learning roadmap (RU) and serves as the main page of the MkDocs site.
 - `dwh-modeling/` contains the article and demo DWH model; SQL lives in `dwh-modeling/sql` as ordered scripts `01_...sql`–`09_...sql` (07–09 are homework DDL, template and solution).
 - `postgres-bookings/` is a Dockerized PostgreSQL + demo “bookings” DB; start it first, then apply DWH scripts against the `demo` database.
 - `mkdocs.yml` — MkDocs Material config; `docs_dir: .` (repo root = site root). Excluded dirs: `project/`, `postgres-bookings/`, `.github/`, `.claude/`.
 - `.github/workflows/deploy-site.yml` — CI/CD: push to `main` → build → deploy to GitHub Pages.
 - `project/` — PRD and ADR (excluded from site).
 ## Build, Test, and Development Commands
 - Start demo Postgres:  
@@ -20,6 +23,45 @@
 - SQL files: keep numeric prefixes (`01_`, `02_`, …) to reflect execution order and use descriptive suffixes like `ddl_*` / `dml_*`.
 - Shell: target `bash`, prefer simple, POSIX-friendly constructs; mirror the style of existing scripts in `postgres-bookings/`.
 ## Markdown Style (dual-compatible: GitHub + MkDocs Material)
 All `.md` files MUST render correctly on both GitHub and the MkDocs Material site. Follow these rules:
 **Headings:**
 - `README.md` (root): start from `##` (H2). Do NOT use `#` (H1) — MkDocs uses H1 as page title, multiple H1s break the right-sidebar TOC.
 - `dwh-modeling/*.md`: may use `#` (H1) since each file is a separate page on the site.
 **Lists:**
 - Always leave a **blank line before the first list item** after a paragraph, heading, or any non-list text. Python-Markdown (MkDocs) requires this; GitHub tolerates its absence but blank lines don't hurt.
 - Use **4-space indentation** for nested lists (not 2-space). GitHub supports both, Python-Markdown requires 4.
 - Example:
  ```markdown
  Some introductory text:
  - Item one
  - Item two
      - Nested item (4 spaces)
  ```
 **Links:**
 - Internal links: always use **relative paths to `.md` files**: `[text](dwh-modeling/SCD.md)`. MkDocs resolves them automatically.
 - Anchor links: use lowercase slugs with single hyphens. Avoid em-dash `—` in headings (it produces `--` in MkDocs slugs vs `-` on GitHub). Use commas or colons instead.
 **Special characters in headings:**
 - OK: colons `:`, commas `,`, parentheses `()`, guillemets `«»` — stripped equally by both platforms.
 - Avoid: em-dash `—`, en-dash `–` — slug behavior differs between GitHub and MkDocs.
 ## MkDocs Site Commands
 - Local preview (user starts, ask user to run via `!`):
  `uv run --with 'mkdocs-material==9.6.14' --with 'mkdocs-same-dir==0.1.3' mkdocs serve`
 - Build with strict validation (catches broken links/anchors):
  `uv run --with 'mkdocs-material==9.6.14' --with 'mkdocs-same-dir==0.1.3' mkdocs build --strict`
 - Visual check via Playwright (when `mkdocs serve` is running on port 8000):
  `npx playwright screenshot --viewport-size='1280,800' 'http://127.0.0.1:8000/#anchor' /path/to/screenshot.png`
  Then read the screenshot with the Read tool to inspect rendering. Use `--viewport-size='1280,2000'` for tall pages.
 - Kill stuck dev server: `lsof -ti :8000 | xargs kill`
 - Site URL: `https://dementev-dev.github.io/de-roadmap/`
 ## Testing Guidelines
 - There is no dedicated test framework; treat SQL scripts as executable documentation.
 - For `dwh-modeling/sql`, run scripts sequentially and rerun `04_validation.sql` after changes to ensure the demo model still loads and basic checks pass.
@@ -1,7 +1,8 @@
-# О роадмапе
+## О роадмапе
 Этот роадмап — конспект моих подходов к обучению Data Engineering.  
 Он подойдёт тем, кто хочет:
 - системно войти в профессию с нуля или близкого к нулю уровня;
 - закрыть пробелы в базе (SQL, Git, Python, DWH, Airflow, Greenplum);
 - подготовиться к собеседованиям и первым рабочим задачам.
@@ -9,7 +10,7 @@
 Роадмап можно проходить самостоятельно или вместе со мной в формате менторства.  
 Если хотите идти с поддержкой ментора — напишите в Telegram: [@dementev_dev](https://t.me/dementev_dev).
-## Оглавление
+### Оглавление
 - [Основные знания](#основные-знания) — Git, SQL, Python, методологии, Docker
 - [Практика и инструменты](#практика-и-инструменты) — Airflow, Greenplum, курсовая работа
@@ -19,26 +20,29 @@
 - [Дополнительные материалы](#дополнительные-материалы)
 Рекомендуемый способ использования:
 - двигаться по разделам последовательно, не перепрыгивая через базу;
 - выполнять практику и домашки, а не только смотреть материалы;
 - возвращаться к разделам по мере появления реальных задач.
 ---
-# Основные знания
+## Основные знания
 [[к оглавлению]](#оглавление)
-## Git и базовые инструменты
+### Git и базовые инструменты
-### База по Git
+#### База по Git
 Что такое контроль версий, когда используется, ПОЧЕМУ и как мы в обучении будем использовать.
 Как создать репозиторий на GitHub, сохранять в нем изменения.
 - [Что такое Git для Начинающих / GitHub за 30 минут / Git Уроки - Youtube](https://www.youtube.com/watch?v=VJm_AjiTEEc)
 - [Git: Конфликты для Начинающих // Git Cherry Pick, Git Revert, Git Reset - Youtube](https://www.youtube.com/watch?v=F7FnnfnB9YY)
 - Книга [Pro Git](https://git-scm.com/book/ru/v2) - читать главу 1
-### Основы Markdown
+#### Основы Markdown
 - [Язык Markdown и файл README | Git и GitHub для начинающих - Youtube](https://www.youtube.com/watch?v=8lEDTrr-G4U)
 - [Markdown и его возможности: простой способ оформления текста](https://kurshub.ru/journal/blog/markdown-chto-eto/)
 - [Синтаксис Markdown: подробная шпаргалка для веб-разработчиков / Skillbox Media](https://skillbox.ru/media/code/yazyk-razmetki-markdown-shpargalka-po-sintaksisu-s-primerami/)
@@ -46,14 +50,15 @@
 Домашки по остальным темам тренируемся делать в Git, там же пишем документацию.
 **Когда блок Git и базовые инструменты считаем пройденным:**
 - вы уверенно создаёте репозиторий, коммитите изменения и отправляете их на GitHub;
 - имеете представление о работе с ветками: создание, переключение, что такое merge/PR и разруливание простых конфликтов;
 - оформляете базовую документацию в Markdown (README, заголовки, списки, ссылки, кодовые блоки).
-## Базы данных: SQL и моделирование данных
+### Базы данных: SQL и моделирование данных
 SQL и моделирование данных специально идут рядом: сначала учимся уверенно извлекать данные запросами, затем — понимать и проектировать структуру данных, чтобы ETL/витрины были осмысленными.
-### База по SQL
+#### База по SQL
 Книга: [PostgreSQL. Основы языка SQL](https://postgrespro.ru/education/books/sqlprimer) - Глава 1 "Введение в базы данных и SQL" + ДЗ
 Бесплатный тренажер: [Интерактивный тренажер по SQL – Stepik](https://stepik.org/course/63054/promo)  
@@ -65,7 +70,7 @@ SQL и моделирование данных специально идут р
 Для дальнейшей тренировки и поддержания уровня можно использовать [Database - LeetCode](https://leetcode.com/problem-list/database/). Хорошая подборка задачек: [SQL 50 - Study Plan - LeetCode](https://leetcode.com/studyplan/top-sql-50/)
-### Повышение знаний SQL
+#### Повышение знаний SQL
 Смотрим курс от Postgres Pro [DEV1](https://postgrespro.ru/education/courses/DEV1)
 Темы - от "Введение" до "SQL" включительно, "Управление доступом", "Резервное копирование". Для лучшего усваивания материала проделываем все примеры и домашние задания из конспектов лекция.   
@@ -74,6 +79,7 @@ SQL и моделирование данных специально идут р
 Для развития навыков инженера будет полезно лабораторные работы делать не в виртуальной машине, а в docker контейнере. Предложенный (не обязательный) вариант - в каталоге `postgres-bookings` репозитория.
 Для дальнейшего закрепления материала - читаем книгу [PostgreSQL. Основы языка SQL](https://postgrespro.ru/education/books/sqlprimer)
 - Глава 8 - Индексы + ДЗ
 - Глава 9 - Транзакции
 - Глава 10 - Повышение производительности + ДЗ
@@ -81,9 +87,10 @@ SQL и моделирование данных специально идут р
 Вопросы оптимизации запросов хорошо описаны в курсе [QPT](https://postgrespro.ru/education/courses/QPT) от Postgres Pro. Полученные навыки применимы для работы в том числе с Greenplum, и частично, другими БД.
 На момент написания, видеолекции были доступны только для старой версии Postgres 13, но ее вполне достаточно.
-### Моделирование данных
+#### Моделирование данных
 Понимание того, **как устроены данные и зачем они нужны**, — ключ к качественным ETL-процессам.  
 Мы кратко разбираем:
 - Основные подходы: нормализованные (3NF) vs денормализованные (звезда, снежинка)
 - Что такое staging, marts, слои raw / clean / business
 - Как проектировать таблицы под конкретные сценарии использования
@@ -91,6 +98,7 @@ SQL и моделирование данных специально идут р
 Цель — не стать архитектором, а **уметь читать и объяснять структуру данных**, чтобы писать осмысленные запросы и трансформации.
 Материалы (включая демо DWH-модель из этого репозитория):
 - Мартин Клеппман — «Высоконагруженные приложения» - Глава 2: Модели данных и языки запросов. - Для понимания, чем реляционная модель (SQL) отличается от документной (NoSQL) и графовой, и почему для аналитики мы всё ещё любим таблицы
  (Важно: не перепутайте главу 2 с Частью 2 про распределенные данные!).
 - [Яндекс Практикум: что такое нормализация, простыми словами (для самых начинающих)](https://practicum.yandex.ru/blog/chto-takoe-normalizaciya-dannyh/)
@@ -109,13 +117,14 @@ SQL и моделирование данных специально идут р
 - Хорошее общее введение в модели данных дано в статье и докладе от Yandex: [Как мы внедрили свою модель хранения данных — highly Normalized hybrid Model. Доклад Яндекса](https://habr.com/ru/companies/yandex/articles/557140/)
 **Когда блок «Базы данных» считаем пройденным:**
 - вы уверенно пишете запросы с JOIN, агрегатами, подзапросами и CTE;
 - можете подробно объяснить план запроса в Postgres, понимаете где планировщик отработал корректно, а где - есть возможность улучшить;
 - можете объяснить простую модель данных (3NF/звезда) и прочитать схему DWH;
 - решаете типовые задачи уровня SQL live-coding без долгих пауз.
-## Python
+### Python
 - Если совсем не знакомы с Python, начинаем с курса ["Поколение Python": курс для начинающих – Stepik](https://stepik.org/course/58852/info)
 - Изучаем глубже и "оттачиваем" live coding: ["Поколение Python": курс для продвинутых – Stepik](https://stepik.org/course/68343/info)
@@ -149,50 +158,51 @@ SQL и моделирование данных специально идут р
 Цель — уверенно решать простые задачи на Python в формате live-coding; дальше эти навыки пригодятся для создания DAG Airflow.
 **Когда блок Python считаем пройденным:**
 - вы без подсказок пишете небольшие скрипты с циклами, функциями, обработкой ошибок и работой с коллекциями;
 - умеете читать и модифицировать чужой код, в том числе с использованием pandas и DataFrame;
 - уверенно проходите простой live-coding по Python для DE: прочитать CSV/JSON, отфильтровать, сгруппировать данные и посчитать агрегаты.
 - можете отвечать как на простые вопросы собеседований (циклы, списки, словари), так и продвинутые (итераторы, декораторы, управление памятью, базовые понятия ООП)
-## Методологии разработки
+### Методологии разработки
 > **Зачем это разработчику?**
 > 1. **Работа в команде.** Вам нужно понимать «правила игры». Почему задачи двигаются именно так? Зачем мы встречаемся каждое утро на 15 минут? Почему нельзя просто взять задачу из середины списка?
 > 2. **Собеседование и «легенда».** Когда вас спросят: «Как строилась работа в вашей прошлой команде?», вы должны ответить грамотно. Использование правильной терминологии (спринты, груминг, ретроспектива, WIP-лимиты) — это маркер профессионализма. Это показывает, что вы не просто писали код в вакууме, а были частью налаженного процесса.
-### 1. Основы и сравнение подходов
+#### 1. Основы и сравнение подходов
 Для начала нужно понять глобальную разницу между жестким планированием (Waterfall) и гибкой разработкой (Agile).
 - [Waterfall или Agile, Scrum или Kanban: что выбрать](https://habr.com/ru/companies/kaiten/articles/906006/) — *Базовая статья. Читать внимательно, закрывает вопросы и по Waterfall, и по выбору пути.*
 - [Agile, Scrum, Kanban - обзор, отличия, мифы](https://www.youtube.com/watch?v=LhA5aWjHTJw) — *Видео для закрепления. Помогает разложить кашу в голове по полочкам.*
-### 2. Agile: Философия гибкости
+#### 2. Agile: Философия гибкости
 Agile — это не метод, а философия. Scrum и Kanban — это инструменты этой философии.
 - [Scrum vs Kanban: отличия и разница Agile методов](https://kaiten.ru/blog/kanban-vs-scrum/) — *Сравнение двух главных фреймворков. Важно понять, где заканчивается один и начинается другой.*
-### 3. Scrum (Скрам)
+#### 3. Scrum (Скрам)
 Используется, когда мы создаем продукт и работаем спринтами (циклами).
 *Часто встречается в продуктовых командах, где DE работает в связке с Backend/Frontend.*
 - [Методология Scrum: принципы, ценности, этапы](https://kaiten.ru/blog/chto-takoie-scrum-i-kak-ispolzovat/)
-### 4. Kanban (Канбан)
+#### 4. Kanban (Канбан)
 Используется для управления потоком задач и поддержки.
 *Наиболее популярен в Data Engineering и DevOps, так как данные поступают непрерывно, и их сложно «запереть» в двухнедельный спринт.*
 - [Канбан: метод, инструменты и принципы](https://kaiten.ru/blog/cto-takoe-kanban/)
-### Практика: Как это выглядит в жизни
+#### Практика: Как это выглядит в жизни
 Теория — это хорошо, но на работе вы увидите конкретный интерфейс (Jira или Yandex Tracker). Важно понимать, куда нажимать и как двигать задачи.
-#### 1. Jira (Мировой стандарт)
+##### 1. Jira (Мировой стандарт)
 Самый популярный инструмент. Скорее всего, вы столкнетесь именно с ним.
 * [Как работать с Jira на реальных проектах](https://www.youtube.com/watch?v=oPgm-fsHVfM) (15 мин) — *Отличное видео, где показывают базу: как создать задачу, как перетащить её по доске (Kanban) и что писать в комментариях. Смотреть с 04:00, где начинается практика.*
 * [Создание и настройка Scrum-досок в JIRA](https://www.youtube.com/watch?v=u-u8NRyApUs) — *Если хотите увидеть, как выглядит Спринт и Бэклог изнутри.*
-#### 2. Yandex Tracker (Российский стандарт)
+##### 2. Yandex Tracker (Российский стандарт)
 Активно внедряется в крупных компаниях РФ. Логика та же, но интерфейс другой.
 * [Начало работы в Яндекс.Трекере](https://www.youtube.com/watch?v=pdlYiijjn70) (3 мин) — *Супер-короткий официальный гайд. За 3 минуты показывают всё: очереди, доски, карточки.*
 * [Настройка процесса разработки в Tracker](https://www.youtube.com/watch?v=EdKlYJR2ph0&t=397s)** (c 06:37) — *Более глубокий разбор: как выглядит очередь задач разработчика и жизненный цикл тикета.*
@@ -201,14 +211,16 @@ Agile — это не метод, а философия. Scrum и Kanban — э
 > Не бойтесь кнопок. Главное правило любого трекера: **«Взял задачу в работу — переведи статус в In Progress»**. Это сигнал команде, что вы заняты и вас лучше не отвлекать.
 **Когда блок «Методологии разработки» считаем пройденным:**
 - вы в общих чертах можете объяснить разницу Waterfall vs Agile и Scrum vs Kanban;
 - знаете основные мероприятия Scrum (planning / daily / review / retro) и что от вас ожидается на каждом;
 - умеете работать с трекером (Jira/Tracker): создать/уточнить задачу, взять в работу, корректно двигать статусы и оставлять понятные комментарии;
 - умеете своевременно сообщать о блокерах и уточнять требования, если задача «не бьётся» или в ней не хватает входных данных.
-## Технические навыки
+### Технические навыки
 #### Продвинутый Git
 ### Продвинутый Git
 - Сжатый, но емкий видеогайд: [GIT, GitHub, GitLab. Полный АКТУАЛЬНЫЙ гайд ЗА ПОЛТОРА ЧАСА. Без этого выгонят с работы - Youtube](https://www.youtube.com/watch?v=0Y-fneoUIO8)
 - Книга: [Pro Git](https://git-scm.com/book/ru/v2) - главы 
        - 2 Основы Git
@@ -220,48 +232,55 @@ Agile — это не метод, а философия. Scrum и Kanban — э
 Целевой уровень знания - понимание процесса GitFlow. Как создать ветку, влить изменения в другие ветки. Понимание, зачем.
 На собесах обычно не спрашивают, но нужно в работе.
-### Docker
+#### Docker
 - Курс https://karpov.courses/docker
 Основное предназначение для нас - учебные стенды, где мы разбираем и тренируемся с разными технологиями. На работе - иногда пригождается. На собесах спрашивают редко.
-### Запись встреч
+#### Запись встреч
 OBS Studio
 - Руководство по OBS: [OBS Studio - Настройка ОБС для Записи Игр и Стрима | Настройка Микрофона в Обс и т.д - Youtube](https://www.youtube.com/watch?v=bj8VEphZ65U)
 - [Как записывать собеседования](https://docs.google.com/document/d/1qd8uRYlAaZp9c5zpvCVBOvYQCEukGHI9PEPjnjahI1k/)
 **Когда блок технических навыков считаем пройденным:**
 - вы понимаете базовый GitFlow: как организована работа с ветками в команде и как ваши коммиты попадают в прод;
 - используете Docker для учебных стендов: запускаете контейнеры, смотрите логи и при необходимости перезапускаете сервисы;
 - при необходимости умеете настроить запись экрана/созвонов, чтобы сохранять материалы обучения.
 ---
-# Практика и инструменты
+## Практика и инструменты
 [[к оглавлению]](#оглавление)
-## Airflow
+### Airflow
 Apache Airflow — инструмент для оркестрации ETL-процессов.
 Мы используем его для: 
 - планирования задач,
 - отслеживания зависимостей между шагами,
 - визуализации статуса выполнения.
 Материалы:
 - [Учебник по Airflow](https://github.com/dementev-dev/airflow-manual)
 **Когда блок Airflow считаем пройденным:**
 - вы можете объяснить, что такое DAG, задачи, операторы и сенсоры, и как между ними задаются зависимости;
 - на базе учебного стенда подготавливаете, отлаживаете и запускаете свои DAG'и с расписанием и несколькими шагами (например, загрузка данных и последующие трансформации);
 - уверенно смотрите логи, находите место падения и понимаете, как перезапустить задачу.
-## Greenplum
+### Greenplum
 Разбираем, чем Greenplum отличается от PostgreSQL и зачем нужны MPP-хранилища.
-### Фундаментальная теория
+#### Фундаментальная теория
 Прежде чем нажимать кнопки, нужно понять "физику" больших данных. Почему обычный Postgres начинает тормозить?  
 - Мартин Клеппман, "Высоконагруженные приложения":
    - Глава 1. Надежность, масштабируемость. (Разбираемся, чем вертикальное масштабирование отличается от горизонтального).
    - Глава 3 (только конец главы). Читаем разделы:
@@ -269,32 +288,36 @@ Apache Airflow — инструмент для оркестрации ETL-про
      - «Хранение по столбцам» — почему аналитика требует другого способа записи данных на диск.
      - Зачем: Это объясняет, почему Greenplum устроен именно так. Без этого вы будете пытаться работать с ним как с обычным Postgres.
-### Знакомство с Greenplum
+#### Знакомство с Greenplum
 Теперь, понимая теорию, смотрим, как это реализовано в конкретном инструменте.
 - Простое введение: [Greenplum | Что это такое и как оно работает? - Youtube](https://www.youtube.com/watch?v=rLG9Z_HcKPY)
 - [Визуализатор распределения Greenplum](https://gpskew.rzvde.pro/)
 **Курс Yandex по Greenplum** — основной учебный курс, рекомендуется пройти целиком:
 - [Бесплатный курс Yandex Cloud по Greenplum](https://yandex.cloud/ru/training/greenplum)
 - Практику по курсу удобно делать на стенде [airflow-dwh-gp-lab](https://github.com/dementev-dev/airflow-greenplum) — `make up` поднимает рабочий Greenplum с PXF, не нужен облачный кластер.
 - Стенд покрывает основные темы курса: типы таблиц (heap / appendonly), политики дистрибуции, сжатие, PXF, анализ планов выполнения (`EXPLAIN`).
 - Единственное ограничение: cloud-специфичные темы (тема 2 курса — развёртывание в Yandex Cloud) на локальном стенде не покрыты.
 Дополнительно:
 - [Учебный курс по Greenplum от datafinder](https://datafinder.ru/products/uchebnyy-kurs-po-greenplum) — отдельные главы для углубления.
 **Когда блок Greenplum считаем пройденным:**
 - вы понимаете, как данные распределяются по сегментам, что такое skew и как его увидеть;
 - на базе стенда `airflow-dwh-gp-lab` можете загружать и выгружать данные в Greenplum, выполнять запросы и разбирать планы выполнения (`EXPLAIN`);
 - можете объяснить, в чём практическая разница между MPP-хранилищем и одиночным Postgres на уровне типичных задач DE и собеседований.
-## Курсовая работа
+### Курсовая работа
 Курсовая работа — важный майлстоун роадмапа: ваш первый end-to-end data-проект. После неё у вас есть ключевые технические навыки для старта карьеры в Data Engineering.
 Курсовая выполняется на том же стенде [airflow-dwh-gp-lab](https://github.com/dementev-dev/airflow-greenplum), который вы уже использовали для практики по Greenplum.
 **Что внутри:**
 - Стенд содержит DWH с реализованным эталонным срезом (STG → ODS → DDS → DM) — это ваш образец для подражания.
 - Задача — довести DWH до полного, реализовав недостающие загрузки по аналогии с эталоном.
 - Есть готовый план от аналитика (ТЗ с маппингами и бизнес-правилами) — не нужно придумывать, что делать.
@@ -302,11 +325,12 @@ Apache Airflow — инструмент для оркестрации ETL-про
 - Ветка `main` — рабочая (с заготовками для реализации), ветка `solution` — эталон для сверки.
 **Когда блок курсовой работы считаем пройденным:**
 - все загрузки реализованы, DWH заполняется полностью (STG → ODS → DDS → DM);
 - автоматическая проверка (валидационный DAG) проходит без ошибок;
 - вы можете на собеседовании за 5–10 минут рассказать архитектуру проекта, его цели и показать ключевые части кода.
-## Понятие сложности алгоритмов
+### Понятие сложности алгоритмов
 В Data Engineering редко требуется писать сложные алгоритмы, но важно понимать, как оценивать эффективность кода: 
 - в SQL — через объём сканируемых данных, типы JOIN’ов, использование индексов;
@@ -316,15 +340,16 @@ Apache Airflow — инструмент для оркестрации ETL-про
 ---
-# Карьера и менторство
+## Карьера и менторство
 [[к оглавлению]](#оглавление)
-## Менторство по этому роадмапу
+### Менторство по этому роадмапу
 Если вы нашли этот роадмап в интернете и хотите пройти его не в одиночку, а с поддержкой ментора, можно присоединиться ко мне.
 **Что даёт менторство:**
 - структурный план прохождения роадмапа под вашу ситуацию;
 - разбор вопросов по SQL / DWH / Airflow и другим темам из этого документа;
 - разбор домашних заданий и код-ревью;
@@ -335,10 +360,10 @@ Apache Airflow — инструмент для оркестрации ETL-про
 Просто напишите мне в Telegram: [@dementev_dev](https://t.me/dementev_dev)  
 со словами «Хочу пройти роадмап с ментором» — дальше всё обсудим.
-## Подготовка к собеседованиям
+### Подготовка к собеседованиям
 Цель блока — сформировать «опыт от 2 лет» и уметь корректно его показать в резюме и на собеседовании.
-### Помощь в подготовке резюме
+#### Помощь в подготовке резюме
 - Видео от ОМ по составлению резюме
        - [Как накрутить опыт в резюме | «Ультимативный гайд» @digital_ninja](https://www.youtube.com/watch?v=EPuogJuYsvY)
@@ -346,25 +371,26 @@ Apache Airflow — инструмент для оркестрации ETL-про
        - [Как грамотно продать себя на собеседовании / Созвон сообщества - Boosty](https://boosty.to/m0rtymerr/posts/7289cd23-60c6-4010-bb1c-a5b28dac399a)
 - Практика: совместная работа над резюме — ментор помогает переработать опыт, сформировать убедительную карьерную историю и подготовиться к вопросам по ней.
-### Поиск работы и собеседования
+#### Поиск работы и собеседования
 - [Как подтвердить опыт без трудовой / Хабр против работяг](https://www.youtube.com/watch?v=GHqABzA1zi8)
 - Видео по прохождению собеседований из сообщества ОМ — *в подготовке*
 - Практика: мок-собеседования с ментором — тренировка ответов, разбор слабых мест, психологическая подготовка к реальным интервью.
-### Помощь с прохождением испытательного срока
+#### Помощь с прохождением испытательного срока
 - [Как успешно пройти испытательный срок в IT | «Ультимативный гайд» c @digital_ninja - Youtube](https://www.youtube.com/watch?v=r1lWP5rYVdk)
 - [Испытательный срок - доклад - Boosty](https://boosty.to/m0rtymerr/posts/40e7f17e-022b-495c-8d03-dabbe4383b8e)
 **Когда блок подготовки к собеседованиям считаем пройденным:**
 - у вас есть актуальное резюме под DE с понятными примерами проектов вместо «пустого» опыта;
 - вы умеете искать и отбирать вакансии на HH и Habr Карьера, адаптируя отклики под конкретную позицию;
 - вы прошли хотя бы пару мок-собеседований, получили обратную связь и по результатам доработали резюме и стратегию поиска.
 ---
-# Расширенные навыки
+## Расширенные навыки
 Эти темы выходят за рамки базового минимума для старта в Data Engineering, но дают более полное представление об экосистеме.  
 Их цель — понимать, зачем и когда используется тот или иной инструмент, а не осваивать его на уровне администратора или DevOps-инженера.
@@ -380,48 +406,53 @@ Apache Airflow — инструмент для оркестрации ETL-про
 Практика ограничивается минимальным рабочим примером (запуск в Docker, простой пайплайн или SQL-модель).
 Этого достаточно, чтобы уверенно говорить об инструменте на собеседовании и понимать его место в архитектуре — а всё остальное при необходимости осваивается уже на проекте.
-## ClickHouse
+### ClickHouse
 Бесплатный курс https://yandex.cloud/ru/training/clickhouse  
 Платный курс [ClickHouse для аналитика – Stepik](https://stepik.org/course/100210/promo?search=6551441002)  
-## Streaming (NiFi + Kafka)
+### Streaming (NiFi + Kafka)
 NiFi — визуальный конструктор потоков данных, Kafka — распределённая очередь сообщений. Вместе они закрывают типичный сценарий: принять данные, буферизовать, доставить в хранилище.
 Материалы:
 - [Apache NiFi с нуля за 3 часа (Youtube-плейлист)](https://youtube.com/playlist?list=PL4MpKy3QjNp_rOEEibc4Ro8UK4g8vLX6_&si=W_hidjHmBOZ_aUfS) — первые 4 видео, дальше — по желанию
 - [Лучший Гайд по Kafka для Начинающих За 1 Час (Youtube)](https://www.youtube.com/watch?v=hbseyn-CfXY)
 Практика — на стенде [nifi-kafka-postgres-lab](https://github.com/dementev-dev/nifi-kafka-postgres-lab) (Docker Compose с NiFi, Kafka и Postgres):
 - настраиваем в NiFi простой генератор данных и поток в Postgres;
 - строим поток NiFi → Kafka → NiFi → Postgres.
-## Lakehouse (Spark, Iceberg, Trino)
+### Lakehouse (Spark, Iceberg, Trino)
 > Секция в разработке. Lakehouse — отдельное направление в DE, построенное на разделении compute и storage, открытых табличных форматах (Iceberg, Delta) и движках распределённой обработки (Spark, Trino). Этот роадмап фокусируется на классическом DWH-стеке, поэтому полноценный блок пока не готов — ниже только отправные точки для самостоятельного изучения.
 - [DataLearn: «Что такое Apache Spark»](https://youtu.be/Tl9YzC-dQLI) — введение в Spark с нуля, ~40 минут
 - Стенд для экспериментов: [mini-lakehouse-lab](https://github.com/dementev-dev/mini-lakehouse-lab) (Spark + Iceberg + Trino + MinIO)
-## dbt
+### dbt
 dbt (data build tool) — инструмент для трансформации данных в хранилище.
 Мы рассматриваем его как альтернативу «ручному» написанию сложных CTE и для понимания современного подхода к моделированию данных как кода.
 Материалы:
 - [dbt quickstart (официальный гайд)](https://docs.getdbt.com/guides/manual-install?step=1)
 - [Перевод документации dbt на русский](https://docs.getdbt.tech/)
 Практика:
 - Клонировать [jaffle-shop](https://github.com/dbt-labs/jaffle-shop), установить dbt-duckdb, прогнать `dbt build`, `dbt test`, `dbt docs generate && dbt docs serve` — этого достаточно, чтобы увидеть весь цикл.
 **Когда блок расширенных навыков считаем пройденным:**
 - вы можете на собеседовании кратко объяснить, когда уместны Streaming (NiFi/Kafka), ClickHouse, Lakehouse-стек и dbt, и чем они дополняют базовый стек (Postgres, Airflow, Greenplum);
 - понимаете типичные сценарии: потоковые интеграции и очереди (NiFi + Kafka), аналитические витрины и отчёты на ClickHouse, Lakehouse-архитектура (Spark/Iceberg/Trino), трансформации данных как код (dbt);
 - не боитесь увидеть эти инструменты в описании вакансии и можете поддержать содержательный разговор об их месте в архитектуре.
 ---
-# Софт скиллы
+## Софт скиллы
 [[к оглавлению]](#оглавление)
@@ -431,7 +462,7 @@ dbt (data build tool) — инструмент для трансформации
 ---
-# Дополнительные материалы
+## Дополнительные материалы
 [[к оглавлению]](#оглавление)
@@ -448,6 +479,7 @@ dbt (data build tool) — инструмент для трансформации
 - [Книга. Введение в Apache Kafka для системных аналитиков и проектировщиков интеграций](https://systems.education/kafka)
 - [Перевод документации dbt на русский язык](https://docs.getdbt.tech/)
-## Записи ОМ
+### Записи ОМ
 - [Как пройти собеседование на программиста | Ультимативный гайд с ‪@om_nazarov‬ - Youtube](https://www.youtube.com/watch?v=tzSdiYZ52kI)
 - [Как стать программистом в 2025 | «Ультимативный гайд» с ‪@om_nazarov‬](https://www.youtube.com/watch?v=6151ekTOl38)
@@ -3,28 +3,30 @@
 ## Оглавление
- [Что вы уже умеете — и что узнаете здесь](#что-вы-уже-умеете-и-что-узнаете-здесь)
+- [Что вы уже умеете, и что узнаете здесь](#что-вы-уже-умеете-и-что-узнаете-здесь)
 - [1. Введение: почему нельзя просто SELECT из базы заказов?](#1-введение-почему-нельзя-просто-select-из-базы-заказов)
 - [2. Учебный пример: интернет-магазин](#2-учебный-пример-интернет-магазин)
 - [3. Зачем делить DWH на слои?](#3-зачем-делить-dwh-на-слои)
 - [4. Путешествие данных: от STG до DM](#4-путешествие-данных-от-stg-до-dm)
 - [5. Базовые понятия: факты, измерения, SCD](#5-базовые-понятия-факты-измерения-scd)
- [6. Модели данных для слоя DDS: 4 подхода — и когда какой выбрать](#6-модели-данных-для-слоя-dds-4-подхода-и-когда-какой-выбрать)
+- [6. Модели данных для слоя DDS: 4 подхода, и когда какой выбрать](#6-модели-данных-для-слоя-dds-4-подхода-и-когда-какой-выбрать)
 - [7. Практикум: как собрать первую витрину](#7-практикум-как-собрать-первую-витрину)
 - [8. Как выбрать модель данных? Советы от практиков](#8-как-выбрать-модель-данных-советы-от-практиков)
- [9. Эксплуатация: качество данных — это не «опция»](#9-эксплуатация-качество-данных-это-не-опция)
+- [9. Эксплуатация: качество данных, это не «опция»](#9-эксплуатация-качество-данных-это-не-опция)
- [10. Заключение: главное — понимать «почему»](#10-заключение-главное-понимать-почему)
+- [10. Заключение: главное, понимать «почему»](#10-заключение-главное-понимать-почему)
 - [Приложения](#приложения)
 ---
-## Что вы уже умеете — и что узнаете здесь
+## Что вы уже умеете, и что узнаете здесь
 ✅ Уже знаете:  
 - `SELECT`, `JOIN`, `GROUP BY`;  
 - как посчитать сумму/среднее/количество по таблице.
 🆕 Узнаете в этой статье:  
 - **слои хранилища** (STG → ODS → DDS → DM) и *зачем они нужны*;  
 - **факты и измерения** — основные кирпичики аналитики;  
 - **SCD Type 2** — как хранить историю изменений клиента (например, смену email или города);  
@@ -32,6 +34,7 @@
 - **четыре модели данных**: 3NF, Звезда (Star), Data Vault, Anchor Modeling — и когда какую использовать.
 ⛔ **Не будем говорить** здесь о:  
 - физическом хранении (партиции, индексы, ClickHouse-движки);  
 - распределённых кластерах (Kafka, Spark, Airflow — это отдельный курс);  
 - настройке производительности (`EXPLAIN`, кэши и т.п.).  
@@ -47,6 +50,7 @@
 Вы идёте в базу заказов — и… не находите email. Он в CRM. Идёте в CRM — там нет сумм заказов. Возвращаетесь в заказы — сумма есть, но *только текущая цена товара*. А в 2023 году цена была другой!
 Знакомо? Это — **проблема OLTP-систем** (оперативного учёта):  
 - **CRM**, **склад**, **платёжка** — это разные базы;  
 - каждая оптимизирована под *быструю запись операций* («добавить заказ», «списать товар»);  
 - историю там не хранят — email меняется «в лоб»: старое значение перезаписывается.
@@ -75,6 +79,7 @@
 | `promos` | Маркетинг | Акции: `promo_id`, `code` |
 ⚠️ Обратите внимание:  
 - `customer_id = 101` в одном месяце — `a@ex.com`, в другом — `b@ex.com`;  
 - цена на товар `9001` (Phone) в январе — 100 ₽, в феврале — 110 ₽;  
 - `order_items` содержит `price_at_sale` — *цену в момент покупки*, а не текущую.
@@ -197,6 +202,7 @@ flowchart TD
 ### **DM (Data Mart / Gold/ «Витрины»)** — «готово к употреблению»
 Здесь — таблицы и представления для конкретных задач:  
 - `dm.mart_daily_sales` — ежедневные продажи по товарам и сегментам;  
 - `dm.mart_customer_360` — полный портрет клиента: сколько потратил, когда заходил, какие товары любит.
@@ -210,6 +216,7 @@ flowchart TD
 > *«10 января 2024 года клиент из Москвы (сегмент Premium) купил Phone за 100 ₽»*.
 В DWH это разложится на:  
 - **Факт (Fact)** — событие, которое можно измерить: *покупка*.  
  Хранится в `fact_sales`: `quantity = 1`, `amount = 100`.  
 - **Измерения (Dimensions)** — *контекст* факта:  
@@ -262,6 +269,7 @@ erDiagram
 ### SCD Type 2 — как хранить историю
 Клиент №101:  
 - с 1 янв по 15 мая — `email = a@ex.com`, `city = Москва`;  
 - с 16 мая — `email = b@ex.com`, `city = Москва`;  
 - с 1 окт — `email = b@ex.com`, `city = Санкт-Петербург`.
@@ -287,7 +295,7 @@ AND (dim_customer.valid_to IS NULL OR fact_sales.order_date < dim_customer.valid
 ---
-## 6. Модели данных для слоя DDS: 4 подхода — и когда какой выбрать
+## 6. Модели данных для слоя DDS: 4 подхода, и когда какой выбрать
 В DDS мы можем хранить данные по-разному. Это не «правильно/неправильно», а **выбор под задачу**.
@@ -431,6 +439,7 @@ WHERE c.city = 'Москва'
 💡 **Главная мысль:**  
 идентичность, связи и атрибуты живут **в разных таблицах**, поэтому:
 - историю проще хранить;
 - новые источники проще прикручивать;
 - меньше шансов «сломать» старые отчёты.
@@ -663,7 +672,7 @@ GROUP BY d.date_actual, p.product_name,
 ---
-## 9. Эксплуатация: качество данных — это не «опция»
+## 9. Эксплуатация: качество данных, это не «опция»
 Самая красивая архитектура бессмысленна, если в `mart_daily_sales` — нули.  
 Поэтому в каждом слое — **контроль качества (DQ, Data Quality)**.
@@ -706,7 +715,7 @@ SELECT 'OK' WHERE EXISTS (
 ---
-## 10. Заключение: главное — понимать «почему»
+## 10. Заключение: главное, понимать «почему»
 Хранилище данных — это не про «крутые технологии», а про **мышление**:
@@ -283,6 +283,7 @@ LEFT JOIN current_customers c ON n.customer_id = c.customer_id
 ###### Шаг 3: Вставка новых версий
 Для подходящих записей создаём новую версию:
 - `uuid()` — генерируем уникальный ключ для новой версии
 - `current_date` - функция, возвращающая текущую даты
 - `COALESCE(n.effective_date, current_date)` — устанавливаем дату начала действия новой версии
@@ -0,0 +1,73 @@
 site_name: "DE Roadmap — Data Engineering с нуля до middle"
 site_url: https://dementev-dev.github.io/de-roadmap/
 site_description: "Роадмап по Data Engineering: SQL, Python, Airflow, Greenplum и далее"
 site_author: Dmitry Dementev
 repo_url: https://github.com/dementev-dev/de-roadmap
 repo_name: dementev-dev/de-roadmap
 docs_dir: .
 site_dir: site
 exclude_docs: |
  project/
  postgres-bookings/
  .github/
  .claude/
  site/
  AGENTS.md
  CLAUDE.md
  COMMIT_RULES.md
  LICENSE
  .gitignore
  mkdocs.yml
  dwh-modeling/TODO.md
 nav:
  - Роадмап: README.md
  - Моделирование данных:
      - Введение: dwh-modeling/README.md
      - SCD: dwh-modeling/SCD.md
      - Data Vault: dwh-modeling/DataVault.md
      - "Домашка: STG → DDS → DM": dwh-modeling/Homework_Customer_Status_DDS_DM.md
 theme:
  name: material
  language: ru
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Тёмная тема
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Светлая тема
  features:
    - navigation.top
    - navigation.tracking
    - search.suggest
    - search.highlight
    - toc.follow
    - content.code.copy
 markdown_extensions:
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
      permalink: true
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight
  - attr_list
 plugins:
  - same-dir
  - search:
      lang: ru
@@ -0,0 +1,350 @@
 # ADR: Архитектура сайта de-roadmap
 > Архитектурный документ. Проектные цели и требования — в [PRD](./PRD.md).
 ---
 ## 1. Ключевые архитектурные требования
 Из PRD вытекают четыре жёстких ограничения, определяющих выбор инструментов:
 1. **Сайт опционален.** Репозиторий должен полноценно работать без сайта. Удалили конфиг — всё как было.
 2. **Dual-compatible links.** Внутренние ссылки между `.md` файлами должны работать и на GitHub, и на сайте.
 3. **Один файл = один источник правды.** Не должно быть копий или генерируемых `.md`. Редактируем один раз — рендерится везде.
 4. **Zero-effort deploy.** Push в `main` → сайт обновился. Без ручных шагов, без локальной сборки.
 ---
 ## 2. Выбор генератора статического сайта
 ### Рассмотренные варианты
 | Критерий | MkDocs Material | Docusaurus | Hugo | Astro |
 |----------|----------------|------------|------|-------|
 | Язык/экосистема | Python | Node.js (React) | Go | Node.js |
 | Порог входа | Минимальный — `pip install`, один YAML | Средний — npm, React-компоненты | Средний — Go templates | Высокий — фреймворк |
 | Поддержка Markdown «как есть» | Отличная, расширения через плагины | Хорошая, но MDX-ориентирован | Хорошая, но shortcodes вместо стандартного MD | Хорошая |
 | Навигация по длинной странице | TOC sidebar из коробки | Есть, но заточен под многостраничность | Зависит от темы | Зависит от темы |
 | Поиск | Встроенный (lunr.js), работает offline | Algolia (внешний сервис) или плагин | Нет из коробки | Нет из коробки |
 | Тёмная тема | Из коробки, переключатель | Из коробки | Зависит от темы | Зависит от темы |
 | GitHub Pages деплой | Одна команда / готовый Action | Готовый Action | Готовый Action | Готовый Action |
 | Dual-compatible links | Поддерживает с настройкой `use_directory_urls` | Преобразует ссылки, может ломать GitHub | Преобразует ссылки | Преобразует ссылки |
 | Один мейнтейнер, Python-стек | ✅ Идеально | ❌ Node.js | ⚠️ Go, но бинарник | ❌ Node.js |
 ### Решение: MkDocs Material
 **Почему:**
 - Python-based — совпадает со стеком автора, `pip install` и готово.
 - Лучшая из коробки поддержка длинных страниц с TOC — именно наш сценарий.
 - Встроенный поиск без внешних сервисов.
 - Самый простой конфиг — один `mkdocs.yml`.
 - Крупнейшее комьюнити среди генераторов документации, активно развивается.
 - Dual-compatible links решаемы (см. раздел 4).
 **Почему не Docusaurus:** Node.js-зависимость, ориентирован на многостраничные доки с MDX-компонентами — overkill для «красивый рендер Markdown». Преобразование ссылок может конфликтовать с GitHub-форматом.
 **Почему не Hugo:** Быстрый, но Go-шаблоны сложнее отлаживать. Нет встроенного поиска. Для нашего объёма контента скорость сборки не критична.
 **Почему не Astro:** Полноценный веб-фреймворк — избыточен. Подошёл бы, если бы мы строили маркетинговый сайт с интерактивом, но это не текущая цель.
 ---
 ## 3. Структура файлов
 ### Решение открытого вопроса: `docs/` vs корень репо
 **Решение: `docs_dir: .` (корень репо = корень сайта), с исключениями.**
 Причина: не создаём отдельную папку `docs/`, не дублируем и не перемещаем файлы. MkDocs умеет работать с корнем репо как источником, исключая ненужное.
 ```yaml
 # mkdocs.yml (в корне репо)
 docs_dir: .
 ```
 ### Решение открытого вопроса: README.md как index
 **Решение: плагин `awesome-pages` или конфигурация `nav` с явным указанием.**
 MkDocs по умолчанию ищет `index.md`. Но мы хотим сохранить `README.md` (GitHub его рендерит на главной репо). Есть два пути:
 - **Вариант A:** Симлинк `docs/index.md → ../README.md`. Но мы не используем `docs/`.
 - **Вариант B (выбран):** В `mkdocs.yml` явно указать `README.md` как главную:
 ```yaml
 nav:
  - Роадмап: README.md
  - Моделирование данных:
    - Введение: dwh-modeling/README.md
    - SCD: dwh-modeling/SCD.md
    - Data Vault: dwh-modeling/DataVault.md
    - "Домашка: STG → DDS → DM": dwh-modeling/Homework_Customer_Status_DDS_DM.md
 ```
 MkDocs Material корректно обрабатывает `README.md` файлы — рендерит их как `index.html` соответствующей директории.
 ### Исключения из сборки
 Файлы и папки, которые не должны попасть на сайт:
 ```yaml
 exclude_docs: |
  project/          # проектная документация (PRD, ADR)
  postgres-bookings/ # скрипты стенда (не контент сайта)
  AGENTS.md         # конфигурация для AI-агентов
  LICENSE           # лицензия (есть в footer)
  .gitignore
 ```
 ### Итоговая структура репо
 ```
 de-roadmap/
 ├── mkdocs.yml              ← конфиг сайта (единственный новый файл в корне)
 ├── README.md               ← главная страница сайта И главная страница GitHub
 ├── dwh-modeling/
 │   ├── README.md           ← подстраница «Введение в DWH»
 │   ├── SCD.md              ← подстраница
 │   ├── DataVault.md        ← подстраница
 │   └── Homework_*.md       ← подстраница
 ├── postgres-bookings/      ← исключён из сайта
 ├── project/                ← PRD, ADR — исключены из сайта
 │   ├── PRD.md
 │   └── ADR.md
 ├── .github/
 │   └── workflows/
 │       └── deploy-site.yml ← CI/CD pipeline
 ├── AGENTS.md               ← исключён из сайта
 └── LICENSE
 ```
 ---
 ## 4. Стратегия ссылок (Dual Compatibility)
 ### Проблема
 GitHub рендерит ссылки вида `[текст](dwh-modeling/SCD.md)` как переход к файлу.
 MkDocs по умолчанию преобразует `.md` → `.html` и может менять структуру URL.
 ### Решение
 Комбинация настроек MkDocs:
 ```yaml
 use_directory_urls: true  # /dwh-modeling/SCD/ вместо /dwh-modeling/SCD.html
 ```
 И ссылки в Markdown пишем **всегда как относительные пути к `.md` файлам**:
 ```markdown
 <!-- Это работает и на GitHub, и в MkDocs -->
 [Теория про SCD](dwh-modeling/SCD.md)
 [Введение в DWH](dwh-modeling/README.md)
 ```
 MkDocs Material автоматически резолвит `.md` ссылки в правильные URL сайта.
 ### Кириллические якоря
 GitHub генерирует якоря из кириллических заголовков с URL-encoding:
 `## Базы данных` → `#базы-данных`
 MkDocs Material по умолчанию делает то же самое через расширение `toc`:
 ```yaml
 markdown_extensions:
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
      permalink: true
 ```
 **Риск:** поведение может различаться на edge cases (спецсимволы, эмодзи в заголовках). Митигация — на этапе MVP протестировать все существующие якорные ссылки в README.
 ---
 ## 5. CI/CD Pipeline
 ### GitHub Actions Workflow
 ```yaml
 # .github/workflows/deploy-site.yml
 name: Deploy MkDocs to GitHub Pages
 on:
  push:
    branches: [main]
  workflow_dispatch:  # ручной запуск для отладки
 permissions:
  contents: read
  pages: write
  id-token: write
 concurrency:
  group: "pages"
  cancel-in-progress: false
 jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - run: pip install mkdocs-material
      - run: mkdocs build --strict
        # --strict: падает на warnings (битые ссылки, отсутствующие файлы)
      - uses: actions/upload-pages-artifact@v3
        with:
          path: site/
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4
 ```
 ### Что даёт `--strict`
 Сборка упадёт, если:
 - Есть ссылка на несуществующий `.md` файл.
 - Есть битый якорь.
 - Есть warning от MkDocs.
 Это наш автотест ссылок — бесплатно, в CI.
 ---
 ## 6. Конфигурация MkDocs Material
 ### Минимальный `mkdocs.yml` для MVP
 ```yaml
 site_name: "DE Roadmap — Data Engineering с нуля до middle"
 site_url: https://dementev-dev.github.io/de-roadmap/
 site_description: "Роадмап по Data Engineering: SQL, Python, Airflow, Greenplum и далее"
 site_author: Dmitry Dementev
 repo_url: https://github.com/dementev-dev/de-roadmap
 repo_name: dementev-dev/de-roadmap
 docs_dir: .
 site_dir: site
 # Исключаем из сборки
 exclude_docs: |
  project/
  postgres-bookings/
  AGENTS.md
  LICENSE
  .gitignore
  .github/
  site/
 nav:
  - Роадмап: README.md
  - Моделирование данных:
    - Введение: dwh-modeling/README.md
    - SCD: dwh-modeling/SCD.md
    - Data Vault: dwh-modeling/DataVault.md
    - "Домашка: STG → DDS → DM": dwh-modeling/Homework_Customer_Status_DDS_DM.md
 theme:
  name: material
  language: ru
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Тёмная тема
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Светлая тема
  features:
    - navigation.top          # кнопка «наверх»
    - navigation.tracking     # URL обновляется при скролле
    - search.suggest          # подсказки в поиске
    - search.highlight        # подсветка найденного
    - toc.follow              # TOC следит за скроллом
    - content.code.copy       # кнопка копирования кода
 markdown_extensions:
  - toc:
      permalink: true
  - admonition                # сворачиваемые блоки (Спринт 2)
  - pymdownx.details          # для <details>
  - pymdownx.superfences      # вложенные блоки кода
  - pymdownx.highlight        # подсветка синтаксиса
  - attr_list                 # атрибуты для элементов
 plugins:
  - search:
      lang: ru
 ```
 ### Что уже включено в MVP (бесплатно с Material)
 - Тёмная/светлая тема с переключателем.
 - Полнотекстовый поиск на русском.
 - TOC (оглавление) в правом sidebar.
 - Кнопка «наверх» на длинной странице.
 - URL обновляется при скролле (можно дать ссылку на конкретный раздел).
 - Подсветка синтаксиса в блоках кода.
 - Кнопка копирования кода.
 - Ссылка на GitHub-репозиторий в шапке.
 ---
 ## 7. Кастомный домен (Спринт 2)
 Домен `dementev.space` уже есть. Для подключения:
 1. Создать CNAME-запись: `roadmap.dementev.space → dementev-dev.github.io`.
 2. Добавить файл `CNAME` в корень репо с содержимым `roadmap.dementev.space`.
 3. В `mkdocs.yml` обновить `site_url`.
 4. Включить HTTPS в настройках GitHub Pages.
 ---
 ## 8. Риски и митигации
 | Риск | Митигация |
 |------|-----------|
 | `docs_dir: .` подхватывает лишние файлы | `exclude_docs` со списком исключений; `--strict` ловит проблемы |
 | Кириллические якоря ведут себя по-разному | Тестируем все якорные ссылки из README при первом деплое |
 | `README.md` содержит GitHub-специфичный синтаксис | Проверяем рендер; при необходимости используем MkDocs-совместимые альтернативы |
 | Зависимость от `mkdocs-material` | Активный проект (30k+ stars), Python-пакет; при необходимости — заморозить версию в `requirements.txt` |
 | `exclude_docs` — относительно новая фича MkDocs | Альтернатива: `.mkdocsignore` или плагин `mkdocs-exclude`; протестировать на MVP |
 ---
 ## 9. Порядок действий (Спринт 1)
 1. Создать ветку `feature/site`.
 2. Добавить `mkdocs.yml` в корень репо.
 3. Добавить `.github/workflows/deploy-site.yml`.
 4. Добавить `project/PRD.md` и `project/ADR.md`.
 5. Проверить локально: `pip install mkdocs-material && mkdocs serve`.
 6. Протестировать все внутренние ссылки и якоря.
 7. При необходимости — адаптировать ссылки для dual compatibility.
 8. Merge в `main` → автодеплой → проверить `https://dementev-dev.github.io/de-roadmap/`.
 9. Включить GitHub Pages (Settings → Pages → Source: GitHub Actions).
@@ -0,0 +1,168 @@
 # PRD: Сайт для de-roadmap
 > Проектный документ. Техническая архитектура — в отдельном ADR.
 ---
 ## 1. Контекст и мотивация
 ### Текущее состояние
 Роадмап по Data Engineering живёт как GitHub-репозиторий ([dementev-dev/de-roadmap](https://github.com/dementev-dev/de-roadmap)):
 - Основной контент — монолитный `README.md` (~700 строк) с полным учебным планом.
 - Дополнительные материалы — в подпапках (`dwh-modeling/`, `postgres-bookings/`): теория DWH-моделирования, SCD, Data Vault, домашние задания, скрипты.
 - 109 коммитов, контент активно развивается.
 - Основной поток менти приходит через маркетплейс ОМ (Осознанная Меркантильность) — платформу менторства с системой отзывов, ранжированием менторов и модерацией. Участие платное (абонентская плата + аукцион за позицию в выдаче).
 - Роадмап изначально создавался для себя — как конспект подходов к обучению. Со временем стал использоваться и для менти (удобная структура прохождения), и на ознакомительных созвонах с лидами из ОМ (демонстрация программы и подхода к обучению).
 - Отдельного маркетингового продвижения роадмапа не было, органических приходов «по ссылке из интернета» — ноль. Сайта ментора тоже пока нет — приходить некуда.
 ### Проблема
 GitHub README — рабочий, но не презентабельный формат:
 - Нет удобной навигации по длинному документу (только ручной скролл или оглавление-ссылки).
 - Выглядит как «техническая документация», а не как продукт ментора.
 - GitHub README плохо индексируется поисковыми системами — роадмап в таком виде даже потенциально не может привлекать органический трафик и «продавать сам себя».
 - Неудобно давать ссылку потенциальному менти — GitHub-интерфейс отвлекает (issues, commits, файловое дерево).
 - Нет мобильной адаптации контента (GitHub на телефоне — страдание).
 ### Чего НЕ решаем этим проектом
 - **Лидогенерацию и воронку продаж.** Основной поток тёплых лидов идёт через маркетплейс ОМ, и конкурировать с ним по объёму нереалистично — даже топовые менторы не добирают сравнимое количество лидов из других источников. В перспективе сайт может стать элементом маркетинговой воронки (Habr → сайт → менторство), но это отдалённая цель, не влияющая на текущие решения. Сейчас сайт — витрина экспертизы, а не маркетинговый инструмент.
 - **Масштабирование менторского бизнеса.** Сейчас приоритет — выпустить текущих менти, а не набрать новых.
 - **Создание LMS / интерактивного курса.** Формат остаётся «структурированный текст + ссылки», без трекинга прогресса и автопроверок.
 ---
 ## 2. Цели
 | # | Цель | Метрика успеха |
 |---|------|----------------|
 | 1 | Удобная читаемая версия роадмапа | Сайт с навигацией, поиском, мобильной версией |
 | 2 | Репозиторий остаётся полностью рабочим без сайта | Все `.md` файлы читаемы на GitHub, ссылки между ними работают |
 | 3 | Минимальные накладные расходы на поддержку | Обновил `.md` → запушил → сайт обновился автоматически |
 | 4 | Презентабельный вид для демонстрации на созвонах | Ссылка, которую удобно показать лиду из ОМ при обсуждении программы |
 ---
 ## 3. Целевая аудитория
 **Основная:** менти (текущие и потенциальные) — джуны и переходящие в DE из смежных областей. Приходят по рекомендации из ОМ или по прямой ссылке от ментора. Им нужно быстро оценить объём программы и найти нужный раздел.
 **Вторичная:** коллеги-инженеры, которые наткнулись на репозиторий через GitHub/поиск. Для них важна полнота контента и техническая достоверность, а не «продающие» элементы.
 ---
 ## 4. Требования
 ### 4.1. Обязательные (MVP)
 **Контент и структура:**
 - [ ] Главная страница сайта = полный текст текущего `README.md` (одна длинная страница, не разбиваем).
 - [ ] Подстраницы из существующих `.md` файлов (`dwh-modeling/README.md`, `SCD.md`, `DataVault.md`, домашки).
 - [ ] Автоматическое оглавление (Table of Contents) по заголовкам H2/H3 на главной странице.
 - [ ] Внутренние ссылки работают и на GitHub, и на сайте (dual-compatible links).
 **Навигация:**
 - [ ] Боковая панель с разделами сайта (основной README + подразделы).
 - [ ] Оглавление текущей страницы (правый sidebar / TOC).
 - [ ] Полнотекстовый поиск по сайту.
 **Деплой:**
 - [ ] Автоматическая сборка и публикация при пуше в `main`.
 - [ ] Бесплатный хостинг (GitHub Pages).
 **Совместимость с репо:**
 - [ ] Все `.md` файлы остаются читаемыми на GitHub «как есть».
 - [ ] `README.md` в корне репо продолжает рендериться на главной странице репозитория.
 - [ ] Добавление сайта не ломает существующую структуру — если удалить конфиг сайта, репо работает как раньше.
 ### 4.2. Желательные (Спринт 2+)
 - [ ] Кастомный домен (например, `roadmap.dementev.space`).
 - [ ] Тёмная тема (переключатель light/dark).
 - [ ] Сворачиваемые блоки (collapsible sections / admonitions) для длинных списков материалов.
 - [ ] Кнопка «Написать в Telegram» (floating или в footer) — не агрессивный CTA, просто удобство.
 - [ ] Иконки/бейджи для статуса разделов (пройден / в процессе / не начат) — пока декоративные, без бэкенда.
 - [ ] Яндекс.Метрика или аналогичная аналитика (понимать, сколько людей заходят).
 ### 4.3. Явно НЕ делаем
 - Разбивку основного README на отдельные страницы.
 - Интерактивный трекинг прогресса менти.
 - Систему авторизации / личный кабинет.
 - Блог или раздел новостей (для этого есть Telegram-канал).
 - SEO-оптимизацию и маркетинговые landing pages.
 ---
 ## 5. Ограничения
 - **Бюджет: 0 ₽** (кроме домена, если решим подключить кастомный — `dementev.space` уже есть).
 - **Время на поддержку: минимальное.** Рабочий процесс = «редактирую `.md` → push → сайт обновляется». Не должно быть отдельного шага сборки, ручного деплоя или npm-зависимостей, требующих обновления.
 - **Стек автора: Python-first.** Решение на Python-тулинге предпочтительнее, чем на Node.js/Ruby (проще отлаживать при необходимости).
 - **Один мейнтейнер.** Сайт поддерживает один человек — сложность решения должна быть соответствующей.
 ---
 ## 6. Итерации
 ### Спринт 1 — MVP: «Сайт, который просто работает»
 **Scope:**
 - Конфигурация генератора статического сайта.
 - CI/CD pipeline (GitHub Actions → GitHub Pages).
 - Главная страница = README.
 - Подстраницы из `dwh-modeling/`.
 - Фикс внутренних ссылок для dual compatibility.
 **Definition of Done:**
 - Сайт доступен по URL `https://dementev-dev.github.io/de-roadmap/`.
 - Все ссылки внутри README работают и на сайте, и на GitHub.
 - При пуше в `main` сайт автоматически пересобирается за < 2 минут.
 - Контент на GitHub выглядит ровно так же, как до добавления сайта.
 ### Спринт 2 — «Удобство и навигация»
 **Scope:**
 - Кастомный домен.
 - Тёмная тема.
 - Сворачиваемые блоки для длинных секций.
 - Кнопка «Написать ментору» (Telegram).
 - Базовая аналитика.
 ### Спринт 3 — «Контент и визуал» (по необходимости)
 **Scope:**
 - Визуальная карта роадмапа (интерактивная диаграмма прохождения).
 - Страница «О менторе» / «Отзывы выпускников» (когда будут выпускники).
 - Расширение контента: новые разделы роадмапа → автоматически появляются на сайте.
 ---
 ## 7. Риски
 | Риск | Вероятность | Влияние | Митигация |
 |------|-------------|---------|-----------|
 | Ссылки ломаются при конвертации (GitHub vs сайт) | Средняя | Высокое | Стратегия dual-compatible links в ADR; автотест ссылок в CI |
 | Кириллические якоря рендерятся по-разному | Средняя | Среднее | Тестирование конкретного генератора; при необходимости — латинские id |
 | Генератор сайта перестаёт поддерживаться | Низкая | Среднее | Контент в plain Markdown — миграция на другой генератор за день |
 | Накладные расходы на поддержку растут | Низкая | Среднее | Принцип «сайт опционален»: если мешает — удаляем конфиг, репо работает |
 | GitHub Pages ограничения (bandwidth, размер) | Очень низкая | Низкое | Для статического сайта с текстом — не актуально |
 ---
 ## 8. Открытые вопросы
 1. **Домен.** Использовать GitHub Pages URL или сразу подключить кастомный домен? Можно решить в Спринте 2.
 2. **README.md в корне vs docs/.** Оставляем README.md в корне (GitHub его рендерит) и используем его же как `index.md` для сайта, или делаем симлинк / копию? → Решение в ADR.
 3. **Структура `docs/` директории.** Нужно ли вообще создавать `docs/`, или генератор может работать прямо с корнем репо? → Решение в ADR.