Перейти к содержанию

Главная

Демонстрация работы автогенерации сайта на github-pages/gitlab.pages с использованием mkdocs.

Что же это?

Пишите страницы в markdown, а генератор статичного сайта mkdocs с темой mkdocs-material соберут нестыдный статичный сайт с оформлением, навигацией, поиском, содержанием и тп. А если использовать github-pages или gitlab.pages, то этот сайт автоматически соберется, опубликуется и будет доступен с учетом видимости проекта.

GitHub Pages

Смотрите пример репозитория на GitHub https://github.com/Stepa86/demo_mkdocs/ и пример сайта https://stepa86.github.io/demo_mkdocs/

  1. Готовый файл пайплайна уже есть в репозитории: .github\workflows\gh-pages.yml

  2. В настройках репо нужно включить использование Actions. https://github.com/<username>/<repository>/settings/actions . Для этого репо путь такой, но у вас нет прав на настройки: https://github.com/Stepa86/demo_mkdocs/settings/actions

    Картинка

    Setting-GA

  3. После пуша в мастер (если вы не меняли триггер для запуска пайплайна) запустится сборка и через некоторое время будет опубликован статический сайт <username>.github.io/<repository>. Адрес сайта можно посмотреть в настройках https://github.com/<username>/<repository>/settings.

    Картинка

    Setting-GP

Так же смотрите инструкцию на странице mkdocs-material

GitLab Pages

Смотрите пример репозитория на GitLab https://gitlab.com/Stepa86/demo_mkdocs и пример сайта https://stepa86.gitlab.io/demo_mkdocs/

  1. Готовый файл пайплайна уже есть в репозитории: .gitlab-ci.yml
  2. После пуша в мастер запустится сборка и публикация. Сайт будет опубликован по адресу <username>.gitlab.io/<repository>
  3. При мерж-реквестах будет выполнятся тестирование - будут проверены ссылки на их существование и корректность настроек

Так же смотрите инструкцию на странице mkdocs-material

Локальный веб-сервер

Должен быть установлен python.

Установка python

Скачиваем питон. Запускаем выборочную установку.

install-python1

Снимаем все галочки, кроме pip.

install-python2

Снимаем все, кроме добавления в переменные окружения.

install-python3

Можно тыкнуть в отключение лимитов в длине пути, но это не обязательно (но это не точно).

Установка/обновление библиотек

Запустить в корне репозитория pip_Install_update.bat или в командной строке выполнить следующий код:

pip install --upgrade mkdocs mkdocs-material pygments-bsl pymdown-extensions mkdocs-minify-plugin mkdocs-awesome-pages-plugin mkdocs-git-revision-date-localized-plugin
pip_Install_update.bat

pip_Install_update

В конце должна появится надпись, что нас достиг саксесс.

Запуск сервиса локально

В корне репозитория запускаем mkdocs_serve.bat или в командной строке, находясь в корне репозитория:

mkdocs serve
mkdocs_serve.bat

mkdocs_serve

На первое предупреждение не пугаемся. Через некоторое время будет выведено сообщение, что сервер поднят по адресу http://127.0.0.1:8000/ и включено отслеживание изменений.

Отслеживание изменений означает, что после каждого сохранения файла в репозитории - статьи, вспомогательных файлов или настроечных - сайт будет сам пересобираться и выводить уже обновленную статью.

Через поднятый локальный сервер удобно смотреть на верстку сайта и контролировать ошибки в настройках, потерянные ссылки итп.

Когда сервер больше не нужен - достаточно закрыть окно комадной панели.

Не страшное предупреждение has no git logs, using current timestamp

Когда создана новая статья, но еще не закоммичена, то сервер ругается вот так: image-20200610201757936 На него можно не обращать внимание или просто закоммитить изменения и предупреждение уйдет.

Предупреждение о битой ссылке

Такое предупреждение означает, что в файле knowledge\Posts\New_page_checklist.md есть ссылка на файл knowledge\Posts\test.md, но самого этого файла не существует. Это битая ссылка и гитлаб не даст влить такую статью. Убедитесь, что регистр букв совпадает и слеши правильные. image-20200610202108342

Ошибка в файле .pages

Если в файле .pages ошибка, то выскочет такая страшная штука, где указано, что в файле E:\GIT_Repo\Konstanta\wiki\docs\knowledge\Posts\.pages неправильно указан порядок, т.к. файл New_post1.md не найден. image-20200610202418995

Полезное ПО

Примеры

Известные проблемы

Оглавление не отображается

Чтобы оглавление отображалось нужно:

  1. Оно не должно быть отключено через метаданные или настойки
  2. Должна быть правильная структура файла. Должен быть заголовок # Заголовок страницы и ## Заголовки разделов первого уровня. Именно по заголовкам раздела строится оглавление.
  3. Если включена опция отображения оглавления встроенная в навигацию (toc.integrate), то для вывода оглавления страница должна входить в навигацию - то есть слева должна отображаться иерархия страниц

Картинки в gh-pages не отображаются, а при mkdocs serve и в других местах все нормально

Эксперементальным путем выяснил, что дело в LFS. Если картинки не включать в LFS, то они начинают отображаться.

Использовано:

https://www.mkdocs.org/

https://github.com/squidfunk/mkdocs-material

https://material.io/resources/icons/

Последнее обновление: 3 января 2021 г.