MkDocs + GitHub Pages
Пример развёртывания статического сайта с помощью MkDocs + GitHub Pages.
Шаг 1
Создаём публичный репозиторий в GitHub. Обязательно сразу добавляем пустой README.
Шаг 2
Копируем URL репозитория.
Шаг 3
Запускаем командную строку (или аналог, например PowerShell): нажимаем сочетание клавиш Win+R и вводим команду cmd. Переходим в директорию проекта с помощью команды cd [название папки]. Клонируем репозиторий с помощью команды git clone [скопированный URL репозитория].
Шаг 4
Устанавливаем Python и pip, если они не установлены.
Документация по установке pip (обычно pip устанавливается вместе с Python)
Шаг 5
С помощью pip устанавливаем MkDocs: используем команду pip install mkdocs.
Шаг 6
С помощью pip устанавливаем расширение material для mkdocs: используем команду pip install mkdocs-material.
Шаг 7
С помощью MkDocs создаём заготовку статического сайта: используем команду mkdocs new [название проекта].
Переходим в папку, которую создал MkDocs, с помощью команды cd [название папки].
Шаг 8
Запускаем IDE (в этом примере используется IntelliJ IDE) и открываем папку, которую создал MkDocs.
Шаг 9
Открываем конфигурационный файл mkdocs.yml. Вводим мета-данные сайта и определяем его структуру. Основные параметры (не обязательно использовать все, но все используемые должны быть корректно заполнены, например - правильная ссылка на сайт):
Пример заполнения mkdocs.yml
Шаг 10
Собираем сайт локально с помощью команды mkdocs serve в командной строке.
Переходим на локально собранный сайт, введя в адресной строке браузера адрес порта 127.0.0.1:8000.
Шаг 11
Коммитим+пушим изменения в репозиторий с помощью IDE.
Шаг 12
В основной ветке репозитория лежат исходники для сайта. Теперь с помощью MkDocs собираем сайт в дополнительной ветке. Для этого используем команду mkdocs gh-deploy.
Видим, что появилась вторая ветка.
На GitHub переходим во вкладку Settings, раздел Pages. Инструмент GitHub Pages по умолчанию включён и уже сгенерировал сайт из новой ветки, разместив его на сервере GitHub.
Переходим на сайт по ссылке.
Шаг 13
На сайте расширения material для MkDocs находим и копируем скрипт для автоматизация деплоя. https://squidfunk.github.io/mkdocs-material/publishing-your-site/
На GitHub переходим во вкладку Actions и создаём новый workflow.
Выбираем простой workflow (в списке есть готовые решения для ряда сервисов).
Вводим название ci.yml для нового workflow, очищаем окно и вставляем в него скрипт, скопированный с сайта material. Нажимаем кнопку «Commit cahges».
Теперь каждый раз, когда мы вносим изменения в файлы сайта через IDE и коммитим+пушим их в репозиторий, происходит автоматический деплой изменений на сервер GitHub и сайт обновляется. Течение процесса отображается во вкладке Actions.
В MkDocs из коробки нет подсветки синтаксиса. Чтобы добавить его, включаем в файл mkdocs.yaml следующий код:
Markdown не позволяет задавать размер и выравнивание изображения. Чтобы сделать это, включаем в файл mkdocs.yaml следующий код:
Теперь картинки можно добавлять через конструкции вида (с подписью к изображению):
Last updated