ЛР 1. Статический сайт на MkDocs¶

Тема: Создание и развертывание статического сайта на базе MkDocs с публикацией на GitHub Pages

Цель работы¶

Освоить процесс создания статического сайта с использованием генератора документации MkDocs.
Научиться организовывать структуру документации проекта (портфолио лабораторных работ).
Изучить базовые принципы работы с системой контроля версий Git и платформой GitHub.
Развернуть статический сайт с использованием механизма GitHub Pages на домене username.github.io.
Освоить базовую настройку темы оформления и конфигурационного файла mkdocs.yml.

Задание¶

Создать публичный репозиторий на GitHub.
Настроить GitHub Pages (публикация из каталога /docs ветки main).
Клонировать репозиторий, создать виртуальное окружение, установить MkDocs.
Создать сайт, настроить тему и навигацию.
Создать структуру страниц: главная, об авторе, лабораторные работы.
Выполнить сборку и публикацию.

Ход выполнения¶

Шаг 1. Создание репозитория¶

Создан публичный репозиторий qulin-ds.github.io на GitHub.

Шаг 2. Настройка GitHub Pages¶

В настройках репозитория (Settings → Pages) выбран источник: ветка main, каталог /docs.

Шаг 3. Настройка локального окружения¶

git clone https://github.com/qulin-ds/qulin-ds.github.io.git
cd qulin-ds.github.io
py -m venv venv
.\venv\Scripts\Activate.ps1
pip install mkdocs mkdocs-material

Шаг 4. Создание проекта MkDocs¶

mkdocs new source

Команда создала каталог source (переименован в src) с файлами mkdocs.yml и docs/index.md.

Шаг 5. Выбор и настройка темы¶

Выбрана тема Material for MkDocs по следующим причинам:

Современный дизайн — Material Design обеспечивает чистый и профессиональный вид.
Адаптивность — корректное отображение на мобильных устройствах и десктопе.
Тёмная тема — встроенный переключатель светлой/тёмной схемы.
Навигация — табы, боковое меню и кнопка «наверх».
Расширения — подсветка синтаксиса кода, admonition-блоки, оглавления с якорями.
Популярность — самая используемая тема для MkDocs с отличной документацией.

Шаг 6. Настройка конфигурации¶

Файл src/mkdocs.yml:

site_name: "Артем Мастеров — Портфолио"
site_url: https://qulin-ds.github.io/
site_dir: ../docs

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.tabs
    - navigation.sections
    - navigation.top
    - search.highlight

nav:
  - "Главная": index.md
  - "Об авторе": about.md
  - "1 семестр":
      - "Обзор": labs/sem1/index.md
      - ...
  - "2 семестр":
      - "Обзор": labs/sem2/index.md
      - "ЛР 1. Статический сайт MkDocs": labs/sem2/lab1.md

Шаг 7. Создание структуры страниц¶

src/docs/
├── index.md              # Главная страница
├── about.md              # Об авторе
└── labs/
    ├── sem1/             # Лабораторные 1 семестра
    │   ├── index.md
    │   ├── lab1.md ... lab11.md
    └── sem2/             # Лабораторные 2 семестра
        ├── index.md
        └── lab1.md

Шаг 8. Локальное тестирование¶

cd src
mkdocs serve

Сайт доступен по адресу http://127.0.0.1:8000 для предпросмотра.

Шаг 9. Сборка и публикация¶

mkdocs build -d ../docs
cd ..
git add .
git commit -m "feat: добавлена структура сайта и тема Material"
git push

Выводы¶

В ходе выполнения лабораторной работы были получены следующие навыки:

Создание статического сайта с помощью генератора MkDocs.
Настройка темы оформления Material for MkDocs с поддержкой тёмной темы.
Организация иерархической структуры документации с навигацией по семестрам.
Работа с Git: коммиты, push, ведение истории изменений.
Публикация сайта через GitHub Pages из каталога /docs.

Сайт успешно развёрнут и доступен по адресу: https://qulin-ds.github.io/