diff --git a/.github/ISSUE_TEMPLATE/content_update.yml b/.github/ISSUE_TEMPLATE/content_update.yml index e9378e9..57657b1 100644 --- a/.github/ISSUE_TEMPLATE/content_update.yml +++ b/.github/ISSUE_TEMPLATE/content_update.yml @@ -44,6 +44,6 @@ body: attributes: label: Чеклист Контрибьютора options: - - label: Я буду редактировать контент в docs/, а не в сгенерированном content/ + - label: Я буду редактировать контент в docs/ и пересоберу content manifest - label: Я запущу prepare:content и validate:content перед открытием PR - label: Я добавлю author metadata, если это уместно diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml index d5e4e11..c0b38ee 100644 --- a/.github/workflows/pr-check.yml +++ b/.github/workflows/pr-check.yml @@ -33,6 +33,13 @@ jobs: - name: Prepare generated content run: npm run prepare:content + - name: Upload content report + if: always() + uses: actions/upload-artifact@v4 + with: + name: content-report-json + path: .cache/content-report.json + - name: Validate markdown links and content references run: npm run validate:content diff --git a/.gitignore b/.gitignore index 6d9a85a..2c0687e 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,7 @@ pnpm-debug.log* # Build artifacts *.tsbuildinfo +.cache/ # Python __pycache__/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43d7784..8684785 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,10 +24,10 @@ Основные директории: - `docs/` - исходные материалы, которые редактируются вручную -- `content/` - синхронизированный слой, который использует приложение +- `.cache/content-manifest.json` - build-time manifest, который используют приложение, поиск и валидатор - `resources/` - датасеты и дополнительные артефакты - `public/` - публичные ассеты, включая `search-index.json` -- `scripts/` - синхронизация контента, валидация и сборка поискового индекса +- `scripts/` - сборка content manifest, валидация и сборка поискового индекса - `.github/workflows/` - CI и деплой ## Локальный Запуск @@ -54,7 +54,7 @@ npm run dev 1. Сделайте fork репозитория и создайте ветку от `main`. 2. Вносите изменения с понятной и ограниченной областью. -3. Если меняете документацию, редактируйте `docs/`, а не сгенерированный `content/`. +3. Если меняете документацию, редактируйте `docs/`; manifest пересобирается командой `prepare:content`. 4. Запустите нужные проверки локально. 5. Откройте pull request с понятным описанием и результатами проверки. @@ -78,8 +78,8 @@ npm run validate:content Пайплайн проекта устроен так: 1. `docs/` является редактируемым источником -2. `npm run content:sync` переносит материалы в `content/` -3. `npm run search:build` пересобирает `public/search-index.json` +2. `npm run content:manifest` собирает `.cache/content-manifest.json` +3. `npm run search:build` пересобирает `public/search-index.json` из manifest 4. `npm run prepare:content` выполняет оба шага ## Изменения В Коде @@ -122,7 +122,7 @@ npm run validate:content - сохраняйте понятную и воспроизводимую структуру - отдавайте предпочтение практическим и проверяемым примерам -- добавляйте frontmatter-поля `title`, `description`, `order` и `author`, где это уместно +- добавляйте frontmatter-поля `title`, `description`, `author` и один из `order` / `sidebar_position` для каждой страницы - указывайте язык в code fence - проверяйте ссылки, якоря и файловые ссылки - не добавляйте непроверенный или потенциально небезопасный внешний контент diff --git a/README.md b/README.md index f94a812..140cc34 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,9 @@ Production URL: https://minkinad.github.io/StackMIREA/ Актуально на 4 апреля 2026 года. -- 19 учебных треков в `content/`. +- 19 учебных треков в едином content manifest. - 68 исходных Markdown/MDX-файлов в `docs/`. -- 71 синхронизированная Markdown/MDX-страница. +- 71 Markdown/MDX-страница в `.cache/content-manifest.json`. - 52 отдельных учебных материала без учёта индексных страниц разделов. - Крупнейшие треки: `java` (26 страниц), `ai` (9), `bigdata` (9), `python` (6), `procedural-programming` (6). - Два workflow в CI/CD: `PR Checks` и `Deploy Docs to GitHub Pages`. @@ -39,16 +39,16 @@ Production URL: https://minkinad.github.io/StackMIREA/ ## Как устроен контент - `docs/` - исходные материалы, которые редактируются вручную. -- `content/` - синхронизированный слой, который использует приложение. +- `.cache/content-manifest.json` - единый build-time manifest, который используют приложение, поиск и валидатор. - `resources/` - дополнительные файлы, датасеты и артефакты практик. -- `scripts/` - генерация контента, поискового индекса и валидация ссылок. +- `scripts/` - сборка content manifest, поискового индекса и валидация ссылок. - `public/search-index.json` - локальный поисковый индекс для страницы `/ask`. Основной pipeline: 1. Материалы редактируются в `docs/`. -2. `npm run content:sync` переносит их в `content/`. -3. `npm run search:build` собирает поисковый индекс. +2. `npm run content:manifest` собирает `.cache/content-manifest.json` с slug, frontmatter, author, toc, preview, topics и hash. +3. `npm run search:build` собирает поисковый индекс из manifest. 4. `npm run prepare:content` объединяет оба шага. 5. `npm run build` запускает `prepare:content` автоматически через `prebuild`. @@ -92,8 +92,11 @@ npm run dev - `npm run start` - локальный запуск собранной статической версии на `:3000`. - `npm run lint` - проверка ESLint. - `npm run typecheck` - проверка TypeScript. -- `npm run prepare:content` - синхронизация контента и сборка поискового индекса. -- `npm run content:sync` - перенос `docs/` -> `content/`. +- `npm run prepare:content` - сборка content manifest и поискового индекса. +- `npm run content:manifest` - генерация `.cache/content-manifest.json` из `docs/`. +- `npm run prepare:content:warning` - сборка manifest в warning-режиме без падения по content issues. +- `npm run prepare:content:report` - генерация `content-report.json` с autofix suggestions. +- `npm run content:sync` - compatibility alias для `content:manifest`. - `npm run search:build` - генерация `public/search-index.json`. - `npm run validate:content` - проверка markdown-ссылок, якорей и репозиторных ссылок в code fence. - `npm run export` - информационный скрипт: static export выполняется внутри `next build`. @@ -103,7 +106,6 @@ npm run dev ```text app/ components/ -content/ docs/ lib/ public/ @@ -136,12 +138,12 @@ SUPPORT.md ## Как вносить изменения 1. Добавьте или обновите материал в `docs//...`. -2. Запустите `npm run content:sync` или сразу `npm run prepare:content`. +2. Запустите `npm run content:manifest` или сразу `npm run prepare:content`. 3. Проверьте контент командой `npm run validate:content`. 4. Проверьте проект командами `npm run lint` и `npm run typecheck`. 5. Откройте Pull Request. -Для автора материала можно указать поле `author` во frontmatter: GitHub login или ссылку на профиль. +Для каждого материала требуется поле `author` во frontmatter: GitHub login или ссылка на профиль. Для более подробного процесса контрибуции см. [CONTRIBUTING.md](./CONTRIBUTING.md). @@ -149,4 +151,3 @@ SUPPORT.md - Код проекта распространяется по лицензии MIT. См. [LICENSE](./LICENSE). - Контент сайта, статьи и учебные материалы - CC BY-NC-SA 4.0. См. [CC-BY-NC-SA-4.0](./CC-BY-NC-SA-4.0). - diff --git a/app/docs/[...slug]/page.tsx b/app/docs/[...slug]/page.tsx index 23f9e2e..061d6bc 100644 --- a/app/docs/[...slug]/page.tsx +++ b/app/docs/[...slug]/page.tsx @@ -50,7 +50,7 @@ export default async function DocPage({ params }: DocPageProps) { const buildInfo = getBuildInfo(); const sidebarGroups = getSidebarGroups(); const pagination = getDocPagination(params.slug); - const { content, toc } = await compileDocMdx(doc.body); + const { content } = await compileDocMdx(doc.body, { collectToc: false }); const editUrl = doc.editPath ? `${GITHUB_EDIT_ROOT}/${doc.editPath}` : null; return ( @@ -91,7 +91,7 @@ export default async function DocPage({ params }: DocPageProps) { - + ); diff --git a/components/search/AskStackMirea.tsx b/components/search/AskStackMirea.tsx index da37efb..782a5e5 100644 --- a/components/search/AskStackMirea.tsx +++ b/components/search/AskStackMirea.tsx @@ -257,7 +257,7 @@ export function AskStackMirea() {

Как это работает

    -
  • Индекс собирается на build-time из `content/` и остаётся совместимым с GitHub Pages.
    • +
  • Индекс собирается на build-time из content manifest и остаётся совместимым с GitHub Pages.
  • Поиск учитывает title, description, секцию, чанки контента и словарь тематических синонимов.
  • Результаты ранжируются так, чтобы сверху были страницы с самым близким фрагментом по смыслу.
diff --git a/docs/ai/index.mdx b/docs/ai/index.mdx index d217db7..7f299a9 100644 --- a/docs/ai/index.mdx +++ b/docs/ai/index.mdx @@ -2,6 +2,7 @@ title: "AI" description: "Рабочие тетради по искусственному интеллекту в формате MDX." order: 1 +author: minkinad --- # AI - обзор diff --git a/docs/ai/notebook-01-python-basics.mdx b/docs/ai/notebook-01-python-basics.mdx index 8164fcc..e8cfca0 100644 --- a/docs/ai/notebook-01-python-basics.mdx +++ b/docs/ai/notebook-01-python-basics.mdx @@ -3,6 +3,7 @@ title: "AI Notebook 1 — Основа Python" sidebar_position: 2 description: "Типы данных, условия, циклы и старт работы с NumPy." slug: "/ai/notebook-01-python-basics" +author: minkinad --- **Основа Python. Библиотеки.** diff --git a/docs/ai/notebook-02-numpy-pandas.mdx b/docs/ai/notebook-02-numpy-pandas.mdx index 88d3088..94865bb 100644 --- a/docs/ai/notebook-02-numpy-pandas.mdx +++ b/docs/ai/notebook-02-numpy-pandas.mdx @@ -3,6 +3,7 @@ title: "AI Notebook 2 — NumPy и pandas" sidebar_position: 3 description: "Базовые операции с массивами и таблицами, масштабирование данных." slug: "/ai/notebook-02-numpy-pandas" +author: minkinad --- **NumPy и pandas** diff --git a/docs/ai/notebook-03-metrics-and-knn.mdx b/docs/ai/notebook-03-metrics-and-knn.mdx index 3edad6b..e39fe8f 100644 --- a/docs/ai/notebook-03-metrics-and-knn.mdx +++ b/docs/ai/notebook-03-metrics-and-knn.mdx @@ -3,6 +3,7 @@ title: "AI Notebook 3 — Метрики и KNN" sidebar_position: 4 description: "Метрики качества, расстояния и классификация K ближайших соседей." slug: "/ai/notebook-03-metrics-and-knn" +author: minkinad --- **1.1. Теоретический материал – Функции Python** diff --git a/docs/ai/notebook-04-regression.mdx b/docs/ai/notebook-04-regression.mdx index d7b6316..f864120 100644 --- a/docs/ai/notebook-04-regression.mdx +++ b/docs/ai/notebook-04-regression.mdx @@ -3,6 +3,7 @@ title: "AI Notebook 4 — Регрессия" sidebar_position: 5 description: "Линейные модели, аппроксимация и визуализация регрессионных зависимостей." slug: "/ai/notebook-04-regression" +author: minkinad --- Дата - 22.04.2023 diff --git a/docs/ai/notebook-05-decision-trees.mdx b/docs/ai/notebook-05-decision-trees.mdx index 09d15b2..7533236 100644 --- a/docs/ai/notebook-05-decision-trees.mdx +++ b/docs/ai/notebook-05-decision-trees.mdx @@ -3,6 +3,7 @@ title: "AI Notebook 5 — Деревья решений" sidebar_position: 6 description: "Деревья решений и базовые техники интерпретации классификаторов." slug: "/ai/notebook-05-decision-trees" +author: minkinad --- **Теоретический материал – Деревья принятия решений** diff --git a/docs/ai/notebook-06-genetic-and-annealing.mdx b/docs/ai/notebook-06-genetic-and-annealing.mdx index a549465..ed00f3d 100644 --- a/docs/ai/notebook-06-genetic-and-annealing.mdx +++ b/docs/ai/notebook-06-genetic-and-annealing.mdx @@ -3,6 +3,7 @@ title: "AI Notebook 6 — Генетические и эволюционные sidebar_position: 7 description: "Оптимизация: эволюционные стратегии и имитация отжига." slug: "/ai/notebook-06-genetic-and-annealing" +author: minkinad --- **Теоретический материал – Эволюционные методы** diff --git a/docs/ai/notebook-07-neural-networks.mdx b/docs/ai/notebook-07-neural-networks.mdx index 2670656..94e7d72 100644 --- a/docs/ai/notebook-07-neural-networks.mdx +++ b/docs/ai/notebook-07-neural-networks.mdx @@ -3,6 +3,7 @@ title: "AI Notebook 7 — Нейронные сети" sidebar_position: 8 description: "Персептрон, MLP и базовый цикл обучения нейросети." slug: "/ai/notebook-07-neural-networks" +author: minkinad --- **1.1. Теоретический материал – Нейронные сети** diff --git a/docs/ai/notebook-08-clustering.mdx b/docs/ai/notebook-08-clustering.mdx index 77e588e..114275e 100644 --- a/docs/ai/notebook-08-clustering.mdx +++ b/docs/ai/notebook-08-clustering.mdx @@ -3,6 +3,7 @@ title: "AI Notebook 8 — Кластеризация" sidebar_position: 9 description: "Неподконтрольное обучение и методы группировки данных." slug: "/ai/notebook-08-clustering" +author: minkinad --- **Теоретический материал - Кластеризация** diff --git a/docs/algorithms/getting-started.mdx b/docs/algorithms/getting-started.mdx new file mode 100644 index 0000000..ac5f37d --- /dev/null +++ b/docs/algorithms/getting-started.mdx @@ -0,0 +1,44 @@ +--- +title: Введение +description: Навигация по учебной документации проекта StackMIREA. +order: 2 +slug: /algorithms/getting-started +author: minkinad +--- + +# StackMIREA Docs + +Этот сайт собирает практики в формате учебных модулей. + +Что внутри: + +- раздел `Python` с практиками по ООП/ФВП и отдельным блоком AI-ноутбуков; +- раздел `Java` с 24 задачами: от основ до паттернов проектирования; +- унифицированная структура каждой практики: задание, решение, описание, важные моменты и вывод. + +## Как пользоваться + +1. Выберите трек: `Python` или `Java`. +2. Откройте нужную практику по номеру. +3. Сначала прочитайте задание, затем разберите пример кода. +4. Сопоставьте материал с исходниками в репозитории. + +:::tip +Используйте правый блок **On this page** для быстрого перехода по большим документам. +::: + +## Формат MDX + +Поддерживаются callout-блоки, fenced code и кастомный рендеринг через Shiki: + +```tsx filename="example.mdx" +:::info +Этот блок будет отрисован как ``. +::: +``` + +## Исходники + +- Python: `pr_Python/` +- Java: `docs/java/` и `content/java/` +- GitHub: [minkinad/StackMIREA](https://github.com/minkinad/StackMIREA) diff --git a/docs/algorithms/index.mdx b/docs/algorithms/index.mdx new file mode 100644 index 0000000..ce30fb0 --- /dev/null +++ b/docs/algorithms/index.mdx @@ -0,0 +1,12 @@ +--- +title: Algorithms +description: Вводные и вспомогательные материалы StackMIREA Docs. +order: 1 +author: minkinad +--- + +## Что внутри + +- Введение и навигация по проекту +- MDX-структура и правила оформления +- Связь с Python и Java треками diff --git a/docs/bigdata/index.mdx b/docs/bigdata/index.mdx index c2ea7a2..b1324c4 100644 --- a/docs/bigdata/index.mdx +++ b/docs/bigdata/index.mdx @@ -2,6 +2,7 @@ title: BigData description: Практики по анализу больших данных, ML, классификации и кластеризации. order: 1 +author: minkinad --- # BigData - обзор diff --git a/docs/bigdata/practice-01-introduction.mdx b/docs/bigdata/practice-01-introduction.mdx index 6dd5caa..1b30305 100644 --- a/docs/bigdata/practice-01-introduction.mdx +++ b/docs/bigdata/practice-01-introduction.mdx @@ -2,6 +2,7 @@ title: Практика 1. Введение в BigData description: Базовые операции и знакомство с форматом работы. order: 2 +author: minkinad --- ## Wiki-версия diff --git a/docs/bigdata/practice-02-data-analysis.mdx b/docs/bigdata/practice-02-data-analysis.mdx index 78e5121..1880222 100644 --- a/docs/bigdata/practice-02-data-analysis.mdx +++ b/docs/bigdata/practice-02-data-analysis.mdx @@ -2,6 +2,7 @@ title: Практика 2. Аналитика данных description: Обработка данных и исследовательский анализ в Jupyter Notebook. order: 3 +author: minkinad --- ## Wiki-версия diff --git a/docs/bigdata/practice-03-regression-and-datasets.mdx b/docs/bigdata/practice-03-regression-and-datasets.mdx index 87e6e6f..4c1231a 100644 --- a/docs/bigdata/practice-03-regression-and-datasets.mdx +++ b/docs/bigdata/practice-03-regression-and-datasets.mdx @@ -2,6 +2,7 @@ title: Практика 3. Регрессия и наборы данных description: Работа с несколькими датасетами и построение моделей. order: 4 +author: minkinad --- ## Wiki-версия diff --git a/docs/bigdata/practice-04-insurance-analysis.mdx b/docs/bigdata/practice-04-insurance-analysis.mdx index 44a57c5..36377c7 100644 --- a/docs/bigdata/practice-04-insurance-analysis.mdx +++ b/docs/bigdata/practice-04-insurance-analysis.mdx @@ -2,6 +2,7 @@ title: Практика 4. Анализ данных страхования description: Практика с датасетом по страхованию и подготовкой признаков. order: 5 +author: minkinad --- ## Wiki-версия diff --git a/docs/bigdata/practice-05-classification.mdx b/docs/bigdata/practice-05-classification.mdx index b5a4564..2a0a7d2 100644 --- a/docs/bigdata/practice-05-classification.mdx +++ b/docs/bigdata/practice-05-classification.mdx @@ -2,6 +2,7 @@ title: Практика 5. Классификация description: Построение и оценка моделей классификации. order: 6 +author: minkinad --- ## Wiki-версия diff --git a/docs/bigdata/practice-06-clustering.mdx b/docs/bigdata/practice-06-clustering.mdx index f86bc06..015eb93 100644 --- a/docs/bigdata/practice-06-clustering.mdx +++ b/docs/bigdata/practice-06-clustering.mdx @@ -2,6 +2,7 @@ title: Практика 6. Кластеризация description: Неподконтрольное обучение и анализ кластеров. order: 7 +author: minkinad --- ## Wiki-версия diff --git a/docs/bigdata/practice-07-ensemble-learning.mdx b/docs/bigdata/practice-07-ensemble-learning.mdx index bcdcc60..953ac61 100644 --- a/docs/bigdata/practice-07-ensemble-learning.mdx +++ b/docs/bigdata/practice-07-ensemble-learning.mdx @@ -2,6 +2,7 @@ title: Практика 7. Ансамблевое обучение description: Комбинирование моделей для повышения качества предсказаний. order: 8 +author: minkinad --- ## Wiki-версия diff --git a/docs/bigdata/practice-08-final-report.mdx b/docs/bigdata/practice-08-final-report.mdx index 4aaa4cf..067ce29 100644 --- a/docs/bigdata/practice-08-final-report.mdx +++ b/docs/bigdata/practice-08-final-report.mdx @@ -2,6 +2,7 @@ title: Практика 8. Итоговая работа description: Финальный отчет и итоговые материалы по модулю BigData. order: 9 +author: minkinad --- ## Wiki-версия - требуется доработка diff --git a/docs/business-process-modeling/index.mdx b/docs/business-process-modeling/index.mdx index f0a17fc..16d827d 100644 --- a/docs/business-process-modeling/index.mdx +++ b/docs/business-process-modeling/index.mdx @@ -2,6 +2,7 @@ title: Моделирование бизнес процессов description: Подходы и инструменты для анализа и моделирования бизнес-процессов. order: 1 +author: minkinad --- ## О разделе diff --git a/docs/configuration-management/index.mdx b/docs/configuration-management/index.mdx index 2277b75..6bdba1f 100644 --- a/docs/configuration-management/index.mdx +++ b/docs/configuration-management/index.mdx @@ -2,6 +2,7 @@ title: Конфигурационное управление description: Практики по управлению конфигурацией, версиям и средам разработки. order: 1 +author: minkinad --- ## О разделе diff --git a/docs/data-structures-and-algorithms-part-1/index.mdx b/docs/data-structures-and-algorithms-part-1/index.mdx index a4f494a..a1808c2 100644 --- a/docs/data-structures-and-algorithms-part-1/index.mdx +++ b/docs/data-structures-and-algorithms-part-1/index.mdx @@ -2,6 +2,7 @@ title: Структуры и алгоритмы обработки данных (часть 1) description: Базовые структуры данных и алгоритмы обработки данных, часть 1. order: 1 +author: minkinad --- ## О разделе diff --git a/docs/data-structures-and-algorithms-part-2/index.mdx b/docs/data-structures-and-algorithms-part-2/index.mdx index d869425..25e1b49 100644 --- a/docs/data-structures-and-algorithms-part-2/index.mdx +++ b/docs/data-structures-and-algorithms-part-2/index.mdx @@ -2,6 +2,7 @@ title: Структуры и алгоритмы обработки данных (часть 2) description: Продвинутые структуры и алгоритмы обработки данных, часть 2. order: 1 +author: minkinad --- ## О разделе diff --git a/docs/database-development/index.mdx b/docs/database-development/index.mdx index 983bad3..d91860d 100644 --- a/docs/database-development/index.mdx +++ b/docs/database-development/index.mdx @@ -2,6 +2,7 @@ title: Разработка баз данных description: Проектирование, нормализация, SQL и практики разработки БД. order: 1 +author: minkinad --- ## О разделе diff --git a/docs/internet-of-things/index.mdx b/docs/internet-of-things/index.mdx index 4b6a309..d1adbe7 100644 --- a/docs/internet-of-things/index.mdx +++ b/docs/internet-of-things/index.mdx @@ -2,6 +2,7 @@ title: Интернет вещей description: "Материалы по IoT: устройства, протоколы обмена и интеграции." order: 1 +author: minkinad --- ## О разделе diff --git a/docs/intro.md b/docs/intro.md index 845f31b..d57a480 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -2,6 +2,7 @@ title: Введение description: Навигация по учебной документации проекта StackMIREA. slug: /intro +author: minkinad --- # StackMIREA Docs @@ -38,5 +39,5 @@ slug: /intro ## Исходники - Python: `pr_Python/` -- Java: `docs/java/` и `content/java/` +- Java: `docs/java/` - GitHub: [minkinad/StackMIREA](https://github.com/minkinad/StackMIREA) diff --git a/docs/java/index.mdx b/docs/java/index.mdx new file mode 100644 index 0000000..3e776f9 --- /dev/null +++ b/docs/java/index.mdx @@ -0,0 +1,12 @@ +--- +title: Java +description: 24 Java-практики с решениями в формате задания и разбора. +order: 1 +author: minkinad +--- + +## Что внутри + +- 24 практики по Java +- OOP, интерфейсы, очереди, GUI, MVC, паттерны +- Задание, решение и описание для каждой практики diff --git a/docs/java/overview.md b/docs/java/overview.md index adb93ed..1c75a3a 100644 --- a/docs/java/overview.md +++ b/docs/java/overview.md @@ -3,6 +3,7 @@ title: Java — обзор sidebar_position: 1 description: Карта Java-практик с решениями в формате задания и разбора. slug: /java/overview +author: minkinad --- # Java Практики diff --git a/docs/java/overview.mdx b/docs/java/overview.mdx new file mode 100644 index 0000000..1c75a3a --- /dev/null +++ b/docs/java/overview.mdx @@ -0,0 +1,33 @@ +--- +title: Java — обзор +sidebar_position: 1 +description: Карта Java-практик с решениями в формате задания и разбора. +slug: /java/overview +author: minkinad +--- + +# Java Практики + +Java-трек состоит из 24 практических задач, где для каждой есть задание, решение и описание. + +## Основные темы + +- классы, объекты, инкапсуляция, наследование; +- интерфейсы, коллекции, обобщения и очереди; +- исключения и файловая система; +- GUI и паттерны проектирования; +- итоговый проект на основе системы заказов. + +## Формат модулей + +Каждый модуль содержит: + +- теоретический блок; +- фрагмент кода прямо из решения; +- список файлов, участвующих в задаче; +- практический разбор; +- итоговый вывод. + +## Исходники + +Исходный код задач перенесен в документацию по темам. diff --git a/docs/java/task-01-classes-and-objects.mdx b/docs/java/task-01-classes-and-objects.mdx index d3295f6..5d38ee3 100644 --- a/docs/java/task-01-classes-and-objects.mdx +++ b/docs/java/task-01-classes-and-objects.mdx @@ -3,6 +3,7 @@ title: Task 1 — Классы и объекты sidebar_position: 2 description: Базовое проектирование классов и создание экземпляров. slug: /java/task-01-classes-and-objects +author: minkinad --- ## Задание diff --git a/docs/java/task-02-program-structure.mdx b/docs/java/task-02-program-structure.mdx index 7ed325c..820a3cb 100644 --- a/docs/java/task-02-program-structure.mdx +++ b/docs/java/task-02-program-structure.mdx @@ -3,6 +3,7 @@ title: Task 2 — Структура программы sidebar_position: 3 description: Точка входа и минимальная структура Java-приложения. slug: /java/task-02-program-structure +author: minkinad --- ## Задание diff --git a/docs/java/task-03-constructors-and-encapsulation.mdx b/docs/java/task-03-constructors-and-encapsulation.mdx index 660b061..db61029 100644 --- a/docs/java/task-03-constructors-and-encapsulation.mdx +++ b/docs/java/task-03-constructors-and-encapsulation.mdx @@ -3,6 +3,7 @@ title: Task 3 — Конструкторы и инкапсуляция sidebar_position: 4 description: Инициализация объектов и контроль состояния через инкапсуляцию. slug: /java/task-03-constructors-and-encapsulation +author: minkinad --- ## Задание diff --git a/docs/java/task-04-inheritance-and-composition.mdx b/docs/java/task-04-inheritance-and-composition.mdx index 7ebf6a3..face9d7 100644 --- a/docs/java/task-04-inheritance-and-composition.mdx +++ b/docs/java/task-04-inheritance-and-composition.mdx @@ -3,6 +3,7 @@ title: Task 4 — Наследование и композиция sidebar_position: 5 description: Переиспользование поведения через наследование и композицию. slug: /java/task-04-inheritance-and-composition +author: minkinad --- ## Задание diff --git a/docs/java/task-05-interfaces-and-abstract-classes.mdx b/docs/java/task-05-interfaces-and-abstract-classes.mdx index 9079c8d..fcb3c55 100644 --- a/docs/java/task-05-interfaces-and-abstract-classes.mdx +++ b/docs/java/task-05-interfaces-and-abstract-classes.mdx @@ -3,6 +3,7 @@ title: Task 5 — Интерфейсы и абстрактные классы sidebar_position: 6 description: Контракты поведения и разделение абстракций от реализации. slug: /java/task-05-interfaces-and-abstract-classes +author: minkinad --- ## Задание diff --git a/docs/java/task-06-class-hierarchies.mdx b/docs/java/task-06-class-hierarchies.mdx index 6bb91f3..7b00513 100644 --- a/docs/java/task-06-class-hierarchies.mdx +++ b/docs/java/task-06-class-hierarchies.mdx @@ -3,6 +3,7 @@ title: Task 6 — Иерархии классов sidebar_position: 7 description: Построение связанных сущностей в единой иерархии. slug: /java/task-06-class-hierarchies +author: minkinad --- ## Задание diff --git a/docs/java/task-07-basic-gui.mdx b/docs/java/task-07-basic-gui.mdx index 2c72740..538a3f4 100644 --- a/docs/java/task-07-basic-gui.mdx +++ b/docs/java/task-07-basic-gui.mdx @@ -3,6 +3,7 @@ title: Task 7 — Базовый GUI sidebar_position: 8 description: Создание простого графического интерфейса на Java. slug: /java/task-07-basic-gui +author: minkinad --- ## Задание diff --git a/docs/java/task-08-graphics-and-animation.mdx b/docs/java/task-08-graphics-and-animation.mdx index 196565c..92520da 100644 --- a/docs/java/task-08-graphics-and-animation.mdx +++ b/docs/java/task-08-graphics-and-animation.mdx @@ -3,6 +3,7 @@ title: Task 8 — Графика и анимация sidebar_position: 9 description: Работа с графическими примитивами и обновлением сцены. slug: /java/task-08-graphics-and-animation +author: minkinad --- ## Задание diff --git a/docs/java/task-09-nameable-priceable.mdx b/docs/java/task-09-nameable-priceable.mdx index f74aa27..fa1d9f8 100644 --- a/docs/java/task-09-nameable-priceable.mdx +++ b/docs/java/task-09-nameable-priceable.mdx @@ -3,6 +3,7 @@ title: Task 9 — Интерфейсы Nameable/Priceable sidebar_position: 10 description: Единые API для объектов с именем и ценой. slug: /java/task-09-nameable-priceable +author: minkinad --- ## Задание diff --git a/docs/java/task-10-recursion.mdx b/docs/java/task-10-recursion.mdx index 32d4dcb..976e792 100644 --- a/docs/java/task-10-recursion.mdx +++ b/docs/java/task-10-recursion.mdx @@ -3,6 +3,7 @@ title: Task 10 — Рекурсия sidebar_position: 11 description: Рекурсивные алгоритмы и базовые условия остановки. slug: /java/task-10-recursion +author: minkinad --- ## Задание diff --git a/docs/java/task-11-sorting-students.mdx b/docs/java/task-11-sorting-students.mdx index 8ee8072..3886b07 100644 --- a/docs/java/task-11-sorting-students.mdx +++ b/docs/java/task-11-sorting-students.mdx @@ -3,6 +3,7 @@ title: Task 11 — Сортировка студентов sidebar_position: 12 description: Сортировка и сравнение объектов по метрикам. slug: /java/task-11-sorting-students +author: minkinad --- ## Задание diff --git a/docs/java/task-12-drunkard-game.mdx b/docs/java/task-12-drunkard-game.mdx index 0f79b4a..d4acacf 100644 --- a/docs/java/task-12-drunkard-game.mdx +++ b/docs/java/task-12-drunkard-game.mdx @@ -3,6 +3,7 @@ title: Task 12 — Игра Пьяница sidebar_position: 13 description: Моделирование игры через очереди и коллекции. slug: /java/task-12-drunkard-game +author: minkinad --- ## Задание diff --git a/docs/java/task-13-file-io.mdx b/docs/java/task-13-file-io.mdx index 1c8e5a4..44d8c3a 100644 --- a/docs/java/task-13-file-io.mdx +++ b/docs/java/task-13-file-io.mdx @@ -3,6 +3,7 @@ title: Task 13 — Файловый ввод-вывод sidebar_position: 14 description: Чтение и запись файлов, обработка ошибок I/O. slug: /java/task-13-file-io +author: minkinad --- ## Задание diff --git a/docs/java/task-14-generics-and-queues.mdx b/docs/java/task-14-generics-and-queues.mdx index a6d79f7..fca8b6d 100644 --- a/docs/java/task-14-generics-and-queues.mdx +++ b/docs/java/task-14-generics-and-queues.mdx @@ -3,6 +3,7 @@ title: Task 14 — Generics и очереди sidebar_position: 15 description: Обобщения и безопасная работа с очередями. slug: /java/task-14-generics-and-queues +author: minkinad --- ## Задание diff --git a/docs/java/task-15-mvc-pattern.mdx b/docs/java/task-15-mvc-pattern.mdx index 6ab8b85..2329e1f 100644 --- a/docs/java/task-15-mvc-pattern.mdx +++ b/docs/java/task-15-mvc-pattern.mdx @@ -3,6 +3,7 @@ title: Task 15 — MVC паттерн sidebar_position: 16 description: Разделение модели, представления и контроллера. slug: /java/task-15-mvc-pattern +author: minkinad --- ## Задание diff --git a/docs/java/task-16-exceptions.mdx b/docs/java/task-16-exceptions.mdx index 9920219..d1b133d 100644 --- a/docs/java/task-16-exceptions.mdx +++ b/docs/java/task-16-exceptions.mdx @@ -3,6 +3,7 @@ title: Task 16 — Исключения sidebar_position: 17 description: Обработка исключений и безопасное выполнение кода. slug: /java/task-16-exceptions +author: minkinad --- ## Задание diff --git a/docs/java/task-17-gui-and-exceptions.mdx b/docs/java/task-17-gui-and-exceptions.mdx index 341108e..8f0f830 100644 --- a/docs/java/task-17-gui-and-exceptions.mdx +++ b/docs/java/task-17-gui-and-exceptions.mdx @@ -3,6 +3,7 @@ title: Task 17 — GUI + исключения sidebar_position: 18 description: Связка UI-слоя, доменной логики и пользовательских ошибок. slug: /java/task-17-gui-and-exceptions +author: minkinad --- ## Задание diff --git a/docs/java/task-18-utilities-and-validation.mdx b/docs/java/task-18-utilities-and-validation.mdx index 35934e7..89772ca 100644 --- a/docs/java/task-18-utilities-and-validation.mdx +++ b/docs/java/task-18-utilities-and-validation.mdx @@ -3,6 +3,7 @@ title: Task 18 — Утилиты и валидация sidebar_position: 19 description: Практика с матрицами, калькулятором и проверкой входных данных. slug: /java/task-18-utilities-and-validation +author: minkinad --- ## Задание diff --git a/docs/java/task-19-filesystem-operations.mdx b/docs/java/task-19-filesystem-operations.mdx index b457d82..7b0ef61 100644 --- a/docs/java/task-19-filesystem-operations.mdx +++ b/docs/java/task-19-filesystem-operations.mdx @@ -3,6 +3,7 @@ title: Task 19 — Операции с файловой системой sidebar_position: 20 description: Просмотр директорий и работа с файловым деревом. slug: /java/task-19-filesystem-operations +author: minkinad --- ## Задание diff --git a/docs/java/task-20-calculator-oop.mdx b/docs/java/task-20-calculator-oop.mdx index 7355c19..7aa5109 100644 --- a/docs/java/task-20-calculator-oop.mdx +++ b/docs/java/task-20-calculator-oop.mdx @@ -3,6 +3,7 @@ title: Task 20 — Калькулятор (ООП) sidebar_position: 21 description: ООП-реализация калькулятора с обработкой исключений. slug: /java/task-20-calculator-oop +author: minkinad --- ## Задание diff --git a/docs/java/task-21-queue-adts.mdx b/docs/java/task-21-queue-adts.mdx index ee4c904..f9cd043 100644 --- a/docs/java/task-21-queue-adts.mdx +++ b/docs/java/task-21-queue-adts.mdx @@ -3,6 +3,7 @@ title: Task 21 — Queue ADT sidebar_position: 22 description: Абстрактные типы данных и разные реализации очереди. slug: /java/task-21-queue-adts +author: minkinad --- ## Задание diff --git a/docs/java/task-22-design-patterns.mdx b/docs/java/task-22-design-patterns.mdx index 18ad86d..480d118 100644 --- a/docs/java/task-22-design-patterns.mdx +++ b/docs/java/task-22-design-patterns.mdx @@ -3,6 +3,7 @@ title: Task 22 — Паттерны проектирования sidebar_position: 23 description: Factory, Abstract Factory и MVC в прикладных задачах. slug: /java/task-22-design-patterns +author: minkinad --- ## Задание diff --git a/docs/java/task-23-orders-and-menu.mdx b/docs/java/task-23-orders-and-menu.mdx index 8cb5863..a21850e 100644 --- a/docs/java/task-23-orders-and-menu.mdx +++ b/docs/java/task-23-orders-and-menu.mdx @@ -3,6 +3,7 @@ title: Task 23 — Заказы и меню sidebar_position: 24 description: Моделирование меню, заказов и интерфейсов предметной области. slug: /java/task-23-orders-and-menu +author: minkinad --- ## Задание diff --git a/docs/java/task-24-final-order-system.mdx b/docs/java/task-24-final-order-system.mdx index 737fccf..a9110cc 100644 --- a/docs/java/task-24-final-order-system.mdx +++ b/docs/java/task-24-final-order-system.mdx @@ -3,6 +3,7 @@ title: Task 24 — Финальный проект sidebar_position: 25 description: Расширенная система заказов с менеджерами и клиентскими сущностями. slug: /java/task-24-final-order-system +author: minkinad --- ## Задание diff --git a/docs/object-oriented-programming/index.mdx b/docs/object-oriented-programming/index.mdx index 765ab6c..9ae77b0 100644 --- a/docs/object-oriented-programming/index.mdx +++ b/docs/object-oriented-programming/index.mdx @@ -2,6 +2,7 @@ title: Объектно ориентированное программирование description: "Практики по ООП: классы, наследование, полиморфизм и архитектура." order: 1 +author: minkinad --- ## О разделе diff --git a/docs/procedural-programming/homework-01-basics.mdx b/docs/procedural-programming/homework-01-basics.mdx index 37c781a..0e26be9 100644 --- a/docs/procedural-programming/homework-01-basics.mdx +++ b/docs/procedural-programming/homework-01-basics.mdx @@ -3,6 +3,7 @@ title: ДЗ 1 — Ввод, арифметика и уравнения sidebar_position: 2 description: Пять стартовых задач по консольному вводу, базовой арифметике и простым уравнениям. slug: /procedural-programming/homework-01-basics +author: minkinad --- ## Что внутри diff --git a/docs/procedural-programming/homework-02-formulas-and-branching.mdx b/docs/procedural-programming/homework-02-formulas-and-branching.mdx index b9aa66a..5e8c7c0 100644 --- a/docs/procedural-programming/homework-02-formulas-and-branching.mdx +++ b/docs/procedural-programming/homework-02-formulas-and-branching.mdx @@ -3,6 +3,7 @@ title: ДЗ 2 — Формулы, ветвления и табуляция sidebar_position: 3 description: Задачи на вычисление выражений, проверку области определения и вывод таблиц значений. slug: /procedural-programming/homework-02-formulas-and-branching +author: minkinad --- ## Что внутри diff --git a/docs/procedural-programming/homework-03-files-and-strings.mdx b/docs/procedural-programming/homework-03-files-and-strings.mdx index 42bb458..4a9a7cf 100644 --- a/docs/procedural-programming/homework-03-files-and-strings.mdx +++ b/docs/procedural-programming/homework-03-files-and-strings.mdx @@ -3,6 +3,7 @@ title: ДЗ 3 — Заём, файлы и работа со строками sidebar_position: 4 description: Формулы по кредитам, чтение файлов, фильтрация чисел и сортировка символов. slug: /procedural-programming/homework-03-files-and-strings +author: minkinad --- ## Что внутри diff --git a/docs/procedural-programming/homework-04-functions-and-automation.mdx b/docs/procedural-programming/homework-04-functions-and-automation.mdx index 6dc53b1..9ad2ed4 100644 --- a/docs/procedural-programming/homework-04-functions-and-automation.mdx +++ b/docs/procedural-programming/homework-04-functions-and-automation.mdx @@ -3,6 +3,7 @@ title: ДЗ 4 — Функции, файлы, графика и системы sidebar_position: 5 description: Девять задач на подпрограммы, файлы, псевдографику, матрицы и преобразование чисел. slug: /procedural-programming/homework-04-functions-and-automation +author: minkinad --- ## Что внутри diff --git a/docs/procedural-programming/homework-05-number-theory-and-combinatorics.mdx b/docs/procedural-programming/homework-05-number-theory-and-combinatorics.mdx index e756b3b..cc8be2d 100644 --- a/docs/procedural-programming/homework-05-number-theory-and-combinatorics.mdx +++ b/docs/procedural-programming/homework-05-number-theory-and-combinatorics.mdx @@ -3,6 +3,7 @@ title: ДЗ 5 — НОД, простые числа, индивидуальны sidebar_position: 6 description: Пятое домашнее задание по теории чисел, файлам и перебору перестановок. slug: /procedural-programming/homework-05-number-theory-and-combinatorics +author: minkinad --- ## Что внутри diff --git a/docs/procedural-programming/index.mdx b/docs/procedural-programming/index.mdx index d3e8b24..195ba36 100644 --- a/docs/procedural-programming/index.mdx +++ b/docs/procedural-programming/index.mdx @@ -2,6 +2,7 @@ title: Процедурное программирование description: Домашние работы по процедурному программированию с условиями, кодом и подробным разбором. order: 1 +author: minkinad --- ## О разделе diff --git a/docs/project-management/index.mdx b/docs/project-management/index.mdx index 0bea6c6..8eebfee 100644 --- a/docs/project-management/index.mdx +++ b/docs/project-management/index.mdx @@ -2,6 +2,7 @@ title: Управление проектами description: Планирование, управление рисками, сроками и командной разработкой. order: 1 +author: minkinad --- ## О разделе diff --git a/docs/python/index.mdx b/docs/python/index.mdx new file mode 100644 index 0000000..475b1f5 --- /dev/null +++ b/docs/python/index.mdx @@ -0,0 +1,13 @@ +--- +title: Python +description: Практические работы по Python в формате MDX-документации. +order: 1 +author: minkinad +--- + +## Что внутри + +- Практика 4: OOP и AST +- Практика 5: тестирование и валидация +- Практика 6 и 6.2: комбинаторы и функциональный стиль +- Полный перенос тетрадей в `docs/python` и `content/python` diff --git a/docs/python/overview.mdx b/docs/python/overview.mdx index 253b5e2..77923a7 100644 --- a/docs/python/overview.mdx +++ b/docs/python/overview.mdx @@ -3,6 +3,7 @@ title: "Python — обзор" sidebar_position: 1 description: "Практики Python в формате технической документации." slug: "/python/overview" +author: minkinad --- # Python Практики diff --git a/docs/python/practice-4-oop.mdx b/docs/python/practice-4-oop.mdx index d1985ea..71910c9 100644 --- a/docs/python/practice-4-oop.mdx +++ b/docs/python/practice-4-oop.mdx @@ -3,6 +3,7 @@ title: "Практика 4 — OOP" sidebar_position: 2 description: "Классы, объекты и деревья выражений из рабочей тетради №4." slug: "/python/practice-4-oop" +author: minkinad --- > Источник: `pr_Python/pr_Python/pract4.ipynb` diff --git a/docs/python/practice-5-test-automation.mdx b/docs/python/practice-5-test-automation.mdx index bdc2581..9e6df64 100644 --- a/docs/python/practice-5-test-automation.mdx +++ b/docs/python/practice-5-test-automation.mdx @@ -3,6 +3,7 @@ title: "Практика 5 — Тестовая автоматизация" sidebar_position: 3 description: "Практикум по pytest, coverage, мутационному и property-based тестированию." slug: "/python/practice-5-test-automation" +author: minkinad --- > Источник: `pr_Python/pr_Python/pract5.ipynb` diff --git a/docs/python/practice-6-2-regex-combinators.mdx b/docs/python/practice-6-2-regex-combinators.mdx index df44fcd..0812829 100644 --- a/docs/python/practice-6-2-regex-combinators.mdx +++ b/docs/python/practice-6-2-regex-combinators.mdx @@ -3,6 +3,7 @@ title: "Практика 6.2 — Расширенные комбинаторы r sidebar_position: 5 description: "Дополнительные задания по комбинаторному и функциональному подходу." slug: "/python/practice-6-2-regex-combinators" +author: minkinad --- > Источник: `pr_Python/pr_Python/pract6_2.ipynb` diff --git a/docs/python/practice-6-regex-combinators.mdx b/docs/python/practice-6-regex-combinators.mdx index af342bd..5208d86 100644 --- a/docs/python/practice-6-regex-combinators.mdx +++ b/docs/python/practice-6-regex-combinators.mdx @@ -3,6 +3,7 @@ title: "Практика 6 — Комбинаторы и функциональ sidebar_position: 4 description: "Функции высшего порядка, декораторы и функциональные структуры данных." slug: "/python/practice-6-regex-combinators" +author: minkinad --- > Источник: `pr_Python/pr_Python/pract6.ipynb` diff --git a/docs/react/index.mdx b/docs/react/index.mdx index fa70ada..d0883d9 100644 --- a/docs/react/index.mdx +++ b/docs/react/index.mdx @@ -2,6 +2,7 @@ title: React description: "Материалы по React: компоненты, состояние, маршрутизация и архитектура UI." order: 1 +author: minkinad --- ## О разделе diff --git a/docs/software-application-development-part-1/index.mdx b/docs/software-application-development-part-1/index.mdx index a0b0330..3183bbd 100644 --- a/docs/software-application-development-part-1/index.mdx +++ b/docs/software-application-development-part-1/index.mdx @@ -2,6 +2,7 @@ title: Технология разработки программных приложений (часть 1) description: Методики и практики разработки программных приложений, часть 1. order: 1 +author: minkinad --- ## О разделе diff --git a/docs/software-testing-and-verification/index.mdx b/docs/software-testing-and-verification/index.mdx index 0ef8ed2..6d26403 100644 --- a/docs/software-testing-and-verification/index.mdx +++ b/docs/software-testing-and-verification/index.mdx @@ -2,6 +2,7 @@ title: Тестирование и верификация ПО description: Материалы по тестированию, качеству и верификации программного обеспечения. order: 1 +author: minkinad --- ## О разделе diff --git a/docs/system-administration/index.mdx b/docs/system-administration/index.mdx index 9df3861..4d4519e 100644 --- a/docs/system-administration/index.mdx +++ b/docs/system-administration/index.mdx @@ -2,6 +2,7 @@ title: Системное администрирование description: Администрирование ОС, сетей, сервисов и инфраструктуры. order: 1 +author: minkinad --- ## О разделе diff --git a/docs/systems-analysis-and-conceptual-modeling-part-1/index.mdx b/docs/systems-analysis-and-conceptual-modeling-part-1/index.mdx index 76bb24b..b41f14f 100644 --- a/docs/systems-analysis-and-conceptual-modeling-part-1/index.mdx +++ b/docs/systems-analysis-and-conceptual-modeling-part-1/index.mdx @@ -2,6 +2,7 @@ title: Анализ и концептуальное моделирование систем (часть 1) description: Введение в системный анализ и концептуальное моделирование, часть 1. order: 1 +author: minkinad --- ## О разделе diff --git a/lib/content-manifest.ts b/lib/content-manifest.ts new file mode 100644 index 0000000..d5a64a4 --- /dev/null +++ b/lib/content-manifest.ts @@ -0,0 +1,74 @@ +import fs from "node:fs"; +import path from "node:path"; + +import { z } from "zod"; + +const gitHubPersonSchema = z.object({ + github: z.string().min(1), + profileUrl: z.string().url(), + avatarUrl: z.string().url() +}); + +const tocItemSchema = z.object({ + id: z.string().min(1), + title: z.string().min(1), + depth: z.union([z.literal(2), z.literal(3)]) +}); + +const contentManifestDocSchema = z.object({ + slug: z.array(z.string().min(1)).min(1), + slugKey: z.string(), + href: z.string().startsWith("/docs/"), + title: z.string().min(1), + description: z.string().min(1), + author: gitHubPersonSchema, + order: z.number().int().nonnegative(), + editPath: z.string().nullable(), + sourcePath: z.string().nullable(), + virtualPath: z.string().min(1), + section: z.string().min(1), + sectionTitle: z.string().min(1), + body: z.string(), + toc: z.array(tocItemSchema), + preview: z.string(), + topics: z.array(z.string()), + anchors: z.array(z.string()), + hash: z.string().min(1), + isSectionIndex: z.boolean(), + isGenerated: z.boolean() +}); + +const contentManifestSchema = z.object({ + version: z.literal(1), + generatedAt: z.string().datetime(), + sourceRoot: z.literal("docs"), + docs: z.array(contentManifestDocSchema) +}); + +export type ContentManifestDoc = z.infer; +export type ContentManifest = z.infer; + +const CONTENT_MANIFEST_PATH = path.join(process.cwd(), ".cache", "content-manifest.json"); + +let cachedManifest: ContentManifest | null = null; + +export function getContentManifestPath() { + return CONTENT_MANIFEST_PATH; +} + +export function getContentManifest() { + if (cachedManifest) { + return cachedManifest; + } + + if (!fs.existsSync(CONTENT_MANIFEST_PATH)) { + throw new Error( + `Content manifest was not found at ${path.relative(process.cwd(), CONTENT_MANIFEST_PATH)}. Run "npm run prepare:content" first.` + ); + } + + const rawManifest = JSON.parse(fs.readFileSync(CONTENT_MANIFEST_PATH, "utf8")); + cachedManifest = contentManifestSchema.parse(rawManifest); + + return cachedManifest; +} diff --git a/lib/mdx.ts b/lib/mdx.ts index 8c5b979..cb6fff6 100644 --- a/lib/mdx.ts +++ b/lib/mdx.ts @@ -10,15 +10,20 @@ const mdxComponents = { CodeBlock }; -export async function compileDocMdx(source: string) { +interface CompileDocMdxOptions { + collectToc?: boolean; +} + +export async function compileDocMdx(source: string, options: CompileDocMdxOptions = {}) { const toc: TocItem[] = []; + const collectToc = options.collectToc ?? true; const result = await compileMDX({ source, options: { parseFrontmatter: false, mdxOptions: { - remarkPlugins: [...getMarkdownRemarkPlugins(toc)], + remarkPlugins: [...getMarkdownRemarkPlugins(collectToc ? toc : [])], rehypePlugins: [rehypeSlug] } }, diff --git a/lib/navigation.ts b/lib/navigation.ts index 89587ad..bc49d55 100644 --- a/lib/navigation.ts +++ b/lib/navigation.ts @@ -1,34 +1,8 @@ -import fs from "node:fs"; -import path from "node:path"; -import matter from "gray-matter"; - -import type { GitHubPerson } from "@/lib/authors"; -import { getDefaultDocAuthor, toGitHubPerson } from "@/lib/authors"; +import { getContentManifest } from "@/lib/content-manifest"; +import type { ContentManifestDoc } from "@/lib/content-manifest"; import { getTrackOrder, getTrackTitle } from "@/lib/tracks"; -import { toTitleCase } from "@/lib/utils"; - -export interface DocFrontmatter { - title?: string; - description?: string; - order?: number; - sidebar_position?: number; - author?: string; -} -export interface DocEntry { - slug: string[]; - slugKey: string; - href: string; - title: string; - description: string; - order: number; - editPath: string | null; - section: string; - body: string; - author: GitHubPerson; - isSectionIndex: boolean; - isGenerated: boolean; -} +export type DocEntry = ContentManifestDoc; export interface SidebarGroup { id: string; @@ -47,52 +21,8 @@ interface DocsIndex { sidebarGroups: SidebarGroup[]; } -const CONTENT_ROOT = path.join(process.cwd(), "content"); -const DOCS_SOURCE_ROOT = path.join(process.cwd(), "docs"); - let cachedDocsIndex: DocsIndex | null = null; -function walkMarkdownFiles(rootDirectory: string) { - const files: string[] = []; - const stack = [rootDirectory]; - - while (stack.length > 0) { - const currentDirectory = stack.pop(); - - if (!currentDirectory) { - break; - } - - const entries = fs.readdirSync(currentDirectory, { withFileTypes: true }); - - for (const entry of entries) { - const fullPath = path.join(currentDirectory, entry.name); - - if (entry.isDirectory()) { - stack.push(fullPath); - continue; - } - - if (entry.isFile() && /\.(md|mdx)$/i.test(entry.name)) { - files.push(fullPath); - } - } - } - - return files; -} - -function normalizeSlug(relativePath: string) { - const withoutExtension = relativePath.replace(/\.(md|mdx)$/i, ""); - const parts = withoutExtension.split(path.sep); - - if (parts.at(-1) === "index") { - return parts.slice(0, -1); - } - - return parts; -} - function getSectionOrder(section: string) { return getTrackOrder(section); } @@ -122,55 +52,6 @@ function compareDocs(left: DocEntry, right: DocEntry) { return left.title.localeCompare(right.title); } -function resolveEditPath(relativePath: string) { - const candidates = - relativePath === path.join("algorithms", "getting-started.mdx") - ? ["intro.mdx", "intro.md"] - : [relativePath, relativePath.replace(/\.mdx$/i, ".md")]; - - for (const candidate of candidates) { - const absoluteCandidatePath = path.join(DOCS_SOURCE_ROOT, candidate); - - if (fs.existsSync(absoluteCandidatePath)) { - return candidate.replace(/\\/g, "/"); - } - } - - return null; -} - -function createDocEntry(filePath: string): DocEntry { - const source = fs.readFileSync(filePath, "utf-8"); - const parsed = matter(source); - const relativePath = path.relative(CONTENT_ROOT, filePath); - const slug = normalizeSlug(relativePath); - const slugKey = getSlugKey(slug); - const section = slug[0] ?? "docs"; - const isSectionIndex = slug.length === 1; - const parsedOrder = Number(parsed.data.order ?? parsed.data.sidebar_position); - const safeOrder = Number.isFinite(parsedOrder) ? parsedOrder : isSectionIndex ? 0 : 9999; - const title = parsed.data.title?.toString().trim() || toTitleCase(slug.at(-1) ?? section); - const description = parsed.data.description?.toString().trim() || ""; - const rawAuthor = parsed.data.author?.toString().trim(); - const author = rawAuthor ? toGitHubPerson(rawAuthor) : getDefaultDocAuthor(); - const editPath = resolveEditPath(relativePath); - - return { - slug, - slugKey, - href: `/docs/${slug.join("/")}`, - title, - description, - order: safeOrder, - editPath, - section, - body: parsed.content, - author, - isSectionIndex, - isGenerated: editPath === null - }; -} - function createSidebarGroups(docs: DocEntry[]) { const groupsMap = new Map(); @@ -215,16 +96,7 @@ function createSidebarGroups(docs: DocEntry[]) { } function buildDocsIndex(): DocsIndex { - if (!fs.existsSync(CONTENT_ROOT)) { - return { - docs: [], - docsBySlug: new Map(), - docOrderBySlug: new Map(), - sidebarGroups: [] - }; - } - - const docs = walkMarkdownFiles(CONTENT_ROOT).map(createDocEntry).sort(compareDocs); + const docs = [...getContentManifest().docs].sort(compareDocs); const docsBySlug = new Map(); const docOrderBySlug = new Map(); diff --git a/package-lock.json b/package-lock.json index d16bbd0..1071595 100644 --- a/package-lock.json +++ b/package-lock.json @@ -22,7 +22,8 @@ "remark-directive": "^4.0.0", "remark-gfm": "^4.0.1", "shiki": "^1.24.4", - "tailwind-merge": "^2.6.0" + "tailwind-merge": "^2.6.0", + "zod": "^4.4.2" }, "devDependencies": { "@tailwindcss/typography": "^0.5.16", @@ -8703,6 +8704,15 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/zod": { + "version": "4.4.2", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.2.tgz", + "integrity": "sha512-IynmDyxsEsb9RKzO3J9+4SxXnl2FTFSzNBaKKaMV6tsSk0rw9gYw9gs+JFCq/qk2LCZ78KDwyj+Z289TijSkUw==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, "node_modules/zwitch": { "version": "2.0.4", "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz", diff --git a/package.json b/package.json index e02c49b..735731f 100644 --- a/package.json +++ b/package.json @@ -11,8 +11,11 @@ "start": "npx serve out -p 3000", "lint": "next lint", "typecheck": "tsc --noEmit --incremental false", - "prepare:content": "npm run content:sync && npm run search:build", - "content:sync": "node scripts/sync-content.mjs", + "prepare:content": "npm run content:manifest && npm run search:build", + "prepare:content:warning": "node scripts/content-manifest.mjs --mode=warning && npm run search:build", + "prepare:content:report": "node scripts/content-manifest.mjs --mode=autofix-report", + "content:manifest": "node scripts/content-manifest.mjs --mode=error", + "content:sync": "npm run content:manifest", "search:build": "node scripts/build-search-index.mjs", "validate:content": "node scripts/validate-content.mjs", "prebuild": "npm run prepare:content" @@ -32,7 +35,8 @@ "remark-directive": "^4.0.0", "remark-gfm": "^4.0.1", "shiki": "^1.24.4", - "tailwind-merge": "^2.6.0" + "tailwind-merge": "^2.6.0", + "zod": "^4.4.2" }, "devDependencies": { "@tailwindcss/typography": "^0.5.16", @@ -49,4 +53,7 @@ "engines": { "node": ">=20.0.0" } + + } + diff --git a/public/search-index.json b/public/search-index.json index 8bc6b43..e736ce3 100644 --- a/public/search-index.json +++ b/public/search-index.json @@ -1 +1 @@ -{"version":1,"generatedAt":"2026-04-08T20:02:48.908Z","docs":[{"id":"ai","href":"/docs/ai","slug":["ai"],"section":"ai","sectionTitle":"AI","title":"AI","description":"Рабочие тетради по искусственному интеллекту в формате MDX.","preview":"AI обзор Раздел объединяет 8 рабочих тетрадей по дисциплине «Искусственный интеллект», перенесенных в MDX формат. Материалы идут от базового Python и научных библиотек к классическим ML методам, нейросетям, эволюционным алгоритмам и кластеризации. Что внутри P","keywords":["notebook","python","ai","ml","данных","деревья","методы","раздел","решений","knn","mdx","numpy","pandas","алгоритмам","базового","библиотек","внутри","генетические"],"topics":["python","ai","knn","pandas","numpy","oop","algorithms","clustering","regression"],"chunks":[{"id":"chunk-0","heading":"AI обзор","text":"Раздел объединяет 8 рабочих тетрадей по дисциплине «Искусственный интеллект», перенесенных в MDX формат. Материалы идут от базового Python и научных библиотек к классическим ML методам, нейросетям, эволюционным алгоритмам и кластеризации.","keywords":["ai","mdx","mdx.","ml","python","алгоритмам","базового","библиотек","дисциплине","идут","интеллект","интеллекту"],"topics":["python","ai","oop","algorithms"]},{"id":"chunk-1","heading":"Что внутри","text":"Python, NumPy и pandas для подготовки данных; метрики расстояния, KNN и базовые техники классификации; регрессия и деревья решений; эволюционные методы, нейросети и кластеризация.","keywords":["ai","knn","mdx.","numpy","pandas","python","базовые","внутри","данных","деревья","интеллекту","искусственному"],"topics":["python","knn","pandas","numpy","oop","clustering","regression"]},{"id":"chunk-2","heading":"Ноутбуки","text":"Notebook 1 — Основа Python типы данных, условия, циклы и вводные примеры. Notebook 2 — NumPy и pandas массивы, таблицы и базовая подготовка данных. Notebook 3 — Метрики и KNN расстояния между объектами и классификация ближайших соседей. Notebook 4 — Регрессия линейные модели, аппроксимация и оценка качества. Notebook 5 — Деревья решений деревья решений и работа с классификаторами","keywords":["notebook","ai","деревья","решений","knn","mdx.","numpy","pandas","python","аппроксимация","базовая","ближайших"],"topics":["python","knn","pandas","numpy","oop","regression"]},{"id":"chunk-3","heading":"Ноутбуки","text":". Notebook 6 — Генетические и эволюционные методы оптимизация, генетические алгоритмы и отжиг. Notebook 7 — Нейронные сети персептрон, MLP и основы обучения сети. Notebook 8 — Кластеризация методы группировки данных без учителя.","keywords":["ai","notebook","генетические","методы","mdx.","mlp","алгоритмы","без","группировки","данных","интеллекту","искусственному"],"topics":["ai","algorithms","clustering"]},{"id":"chunk-4","heading":"Как читать раздел","text":"Начните с Notebook 1 и Notebook 2 , если нужно выровнять базу по Python и обработке данных. Для классического ML переходите к Notebook 3 , Notebook 4 и Notebook 5 . Темы оптимизации и более продвинутых подходов собраны в Notebook 6 , Notebook 7 и Notebook 8 .","keywords":["notebook","ai","mdx.","ml","python","базу","более","выровнять","данных.","если","интеллекту","искусственному"],"topics":["python","ai","oop"]}]},{"id":"ai/notebook-01-python-basics","href":"/docs/ai/notebook-01-python-basics","slug":["ai","notebook-01-python-basics"],"section":"ai","sectionTitle":"AI","title":"AI Notebook 1 — Основа Python","description":"Типы данных, условия, циклы и старт работы с NumPy.","preview":"Основа Python. Библиотеки. Дата 25.02.2023 1.1. Теоретический материал – Типы данных Типы данных Все типы данных в Python относятся к одной из 2 х категорий: изменяемые (mutable) и неизменяемые (immutable). Неизменяемые объекты: исловые данные (int, float), bo","keywords":["print","python","type","задача","10","elif","dev","от","plt.plot","range","данных","apple","df","if","import","rng","trapz","массива"],"topics":["python","ai","knn","numpy"],"chunks":[{"id":"chunk-0","heading":"","text":"Типы данных Все типы данных в Python относятся к одной из 2 х категорий: изменяемые (mutable) и неизменяемые (immutable). Неизменяемые объекты: исловые данные (int, float), bool, None, символьные строки (class 'str'), кортежи (tuple). Изменяемые объекты: списки (list), множества (set), словари (dict).","keywords":["ai","данных","типы","python","изменяемые","неизменяемые","объекты","bool","class","dict","float","immutable"],"topics":["python"]},{"id":"chunk-1","heading":"","text":"python x= 3+5.2 7 y= None z= 'a',5,12.345, (2,'b') df= [['Антонова Антонина',34,'ж'],['Борисов Борис',26,'м']] A={1,'title',2,'content'} print(x,' ',type(x),'\\n',y,' ',type(y),'\\n',df,' ',type(df),'\\n',A,' ',type(A),'\\n')","keywords":["type","ai","df","python","12.345","26","3+5.2","34","content","none","notebook","numpy."],"topics":["python"]},{"id":"chunk-2","heading":"","text":"code 39.4 None [['Антонова Антонина', 34, 'ж'], ['Борисов Борис', 26, 'м']] {'content', 1, 2, 'title'}","keywords":["ai","26","34","39.4","code","content","none","notebook","numpy.","python","title","антонина"],"topics":[]},{"id":"chunk-3","heading":"","text":"python x=5 =2 A={ 1,3,7,8} B={2,4,5,10,'apple'} C=A&B df= 'Антонова Антонина',34,'ж' z='type' D=[1,'title',2,'connect'] print(x,' ',type(x),'\\n',A,' ',type(A),'\\n',B,' ',type(B),'\\n',C,' ',type(C),'\\n',df,' ',type(df),'\\n',z,' ',type(z),'\\n',D,' ',type(D),'\\n')","keywords":["type","ai","df","python","10","34","apple","connect","notebook","numpy.","print","title"],"topics":["python"]},{"id":"chunk-4","heading":"","text":"text True {8, 1, 3, 7} {2, 'apple', 4, 5, 10} set() ('Антонова Антонина', 34, 'ж') type [1, 'title', 2, 'connect']","keywords":["ai","10","34","apple","connect","notebook","numpy.","python","set","text","title","true"],"topics":[]},{"id":"chunk-5","heading":"","text":"В коде часто приходится проверять выполнимость или невыполнимость каких то условий. Синтаксис:","keywords":["ai","notebook","numpy.","python","выполнимость","данных","каких","коде","невыполнимость","основа","приходится","проверять"],"topics":[]},{"id":"chunk-6","heading":"","text":"Обратите внимание, что код, который должен выполняться внутри каждого условия, записывается с отступом в 4 пробела от уровня if, elif и else: в питоне области видимости переменных обозначаются отступами.","keywords":["ai","условия","elif","else","if","notebook","numpy.","python","видимости","внимание","внутри","выполняться"],"topics":["python"]},{"id":"chunk-7","heading":"","text":"То есть, отступы позволяют понять, где начинается код, который должен выполняться при выполнении условия в if, и где заканчивается.","keywords":["ai","условия","if","notebook","numpy.","python","выполнении","выполняться","данных","должен","заканчивается.","код"],"topics":[]},{"id":"chunk-8","heading":"","text":"Задача:Вывести на экран является ли переменная х положительной, отрицательной или равна нулю.","keywords":["ai","notebook","numpy.","python","вывести","данных","задача","ли","нулю.","основа","отрицательной","переменная"],"topics":[]},{"id":"chunk-9","heading":"","text":"python x=125 if x<0: print('x отрицательный') elif x==0: print('x равен 0') else: print('x положительный')","keywords":["ai","print","python","125","elif","else","if","notebook","numpy.","данных","основа","отрицательный"],"topics":["python"]},{"id":"chunk-10","heading":"","text":"Задача: Напишите код. Задается х, напечатать какому из интервалов принадлежит: ( infinity, 5), [ 5, 5] или от (5, +infinity)","keywords":["ai","+infinity","infinity","notebook","numpy.","python","данных","задается","задача","интервалов","какому","код."],"topics":[]},{"id":"chunk-11","heading":"","text":"python x=int(input()) if x < 5: print('x пренадлежит интервалу от бесконечности до 5') elif 5