MkDocs + GitHub Pages

Пример развёртывания статического сайта с помощью MkDocs + GitHub Pages.

Шаг 1

Создаём публичный репозиторий в GitHub. Обязательно сразу добавляем пустой README.

Шаг 2

Копируем URL репозитория.

Шаг 3

Запускаем командную строку (или аналог, например PowerShell): нажимаем сочетание клавиш Win+R и вводим команду cmd. Переходим в директорию проекта с помощью команды cd [название папки]. Клонируем репозиторий с помощью команды git clone [скопированный URL репозитория].

Шаг 4

Устанавливаем Python и pip, если они не установлены.

Шаг 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. Вводим мета-данные сайта и определяем его структуру. Основные параметры (не обязательно использовать все, но все используемые должны быть корректно заполнены, например - правильная ссылка на сайт):

# [Обязательное] Название сайта
site_name: MkDocs

# Базовый адрес сайта
site_url: https://www.mkdocs.org/

# Описание сайта. Добавляется в meta в html-заголовке каждой страницы.
site_description: Project documentation with Markdown.

# Автор (или авторы) сайта. Добавляется в html-заголовок каждой страницы.
site_author: MkDocs Team

# Ссылка на репозиторий, в котором хранятся исходные материалы.
repo_url: https://github.com/mkdocs/mkdocs/

# Информация о теме, которая будет применена для сгенерированного сайта.
theme: material

# Структура генерируемого сайта. Формат [название раздела / страницы: название файла md]. По умолчанию файлы md загружаются в папку docs. Изначально там расположен только файл index.md. Допустимы относительные ссылки на файлы. Разбивка на разделы осуществляется с помощью табуляции.
nav:
    - Section1:
        - Chapter1: Section1/file1.md
        - Chapter2: Section1/file2.md
    - Section2:
        - Chapter1: Section2/file1.md
        - Chapter2: Section2/file2.md

# Копирайтинг
copyright: Copyright © 2024

Пример заполнения 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_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

Подробнее здесь.

Markdown не позволяет задавать размер и выравнивание изображения. Чтобы сделать это, включаем в файл mkdocs.yaml следующий код:

markdown_extensions:
  - attr_list
  - md_in_html

Теперь картинки можно добавлять через конструкции вида (с подписью к изображению):

<figure markdown="span">
  ![Image title](https://dummyimage.com/600x400/){ width="300" }
  <figcaption>Image caption</figcaption>
</figure>

Подробнее здесь.

PreviousПравила русского языкаNextLinks

Last updated