Обзор
Я создал статический веб -сайт, используя Mkdocs и развернуто в Гитлаб Страницы Анкет Это то, что я сделал: https://bemn-proof-of-concept.gitlab.io/mkdoc/ Анкет
Таблица содержания
- Mkdocs
- Подготовка
- Вверх и беги
- Добавить новую страницу
- Темация
- Пользовательские ресурсы
- Гитлаб Страницы
- .gitlab-ci.yml
- Стройте и разверните
- Вывод
Mkdocs
MKDOCS – это быстро , Простой и совершенно великолепно Статический генератор сайта, который ориентирован на строительство документации проекта. Исходные файлы документации записаны в Markdown и настроены с одним файлом конфигурации YAML.
На мой взгляд, настройка статического сайта с использованием MKDOCS действительно проста. Легко изменить тему и вставить пользовательские стили/сценарии. Держите это простым, глупым Анкет Это то что мне нужно.
Подготовка
Убедитесь, что у вас есть следующие инструменты:
- Python 3.x и пип . Установите его через исполняемый файл с официального веб -сайта или использование таких инструментов, как Homebrew Анкет
$ python --version Python 3.8.2 $ pip --version pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)
- A Gitlab учетная запись. Вы можете использовать другие услуги, такие как GitHub Pages , Amazon S3 и т. Д.
- (необязательно) Чистовый лист Marckdown .
(Для меня самая сложная часть – как правильно поднять версии Python и Pip. В Mac встроенная версия Python составляет 2,7, но нам нужен Python 3, чтобы установить Pip
..
Вверх и беги
$ pip install mkdocs $ mkdocs --version mkdocs, version 1.1.2
Предполагая, что ваша папка проекта Doc-Project
:
$ mkdocs new doc-project $ cd doc-project
Затем создается проект MKDOCS с помощью следующей структуры папок:
doc-project ├── docs │ └── index.md ├── img │ └── favicon.ico └── mkdocs.yml
Давайте запустим сайт:
$ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory INFO - Documentation built in 1.65 seconds [I 200612 23:30:19 server:334] Serving on http://127.0.0.1:8000
И проверьте это в http://127.0.0.1:8000 !
Добавить новую страницу
Содержимое
Помните, что все документы должны разместить под док
. Давайте создадим обзорную страницу:
$ cd docs $ touch overview.md
После этого добавьте немного контента в Обзор.md
Анкет
Меню
Если вы хотите, чтобы посетители достигли страницы обзора, вам нужно добавить URL в меню. Давайте редактировать mkdocs.yml
, файл конфигурации сайта:
# In mkdocs.yml... site_name: Doc Project ## change your site name here. nav: - Home: index.md - Overview: overview.md ## add this line.
Вы увидите новую ссылку под названием Обзор в меню. Если вы хотите установить имя своего сайта сейчас, измените значение site_name
Анкет
Ну это все. Вот как добавить новую страницу.
Темация
Вы можете применить индивидуальную тему к MKDOCS. Эта страница Содержит множество тем, предоставленных сообществом.
В этом разделе я применю Тема дизайна материала на мой сайт MKDOCS.
Прекратите запускать свой сайт и установить тему на:
$ pip install mkdocs-material
Обновите mkdocs.yml
очередной раз:
# In mkdocs.yml... site_name: Doc Project nav: - Home: index.md - Overview: overview.md ## Add this section theme: name: material palette: ## Add this sub-section if you want to change the theme color scheme: amber primary: amber accent: orange
Начните сайт:
$ mkdocs serve
Вы увидите, что MKDOCS одевает тему дизайна материала янтарного материала.
Пользовательские ресурсы
Иногда вы можете добавить пользовательские CSS или JS. В MKDOCS вы можете сделать это, добавив extra_css
и extra_javascript
разделы в mkdocs.yml
Анкет
Я создал Каталог
Страница, которая содержит таблицу, написанную в Markdown. Также я хочу подать заявку jQuery DataTables Чтобы сделать стол более интерактивным. Поэтому я добавил связанные библиотеки JS и соответствующий файл CSS в MKDOCS. Вы можете увидеть результат Здесь Анкет
Использование: Создать Catalog.md
Файл и добавьте в него таблицу разметки.
Далее добавьте разделы пользовательских ресурсов в файл конфигурации:
# In mkdocs.yml... site_name: Doc Project nav: - Home: index.md - Catalog: catalog.md ## The catalog page you created in the exercise. theme: name: material palette: scheme: amber primary: amber accent: orange ## Custom js files. extra_javascript: - https://code.jquery.com/jquery-3.5.1.min.js - https://cdn.datatables.net/1.10.21/js/jquery.dataTables.min.js - scripts/site.js ## Custom css files. extra_css: - https://cdn.datatables.net/1.10.21/css/jquery.dataTables.min.css
Создайте пользовательский файл JS:
$ cd docs $ mkdir scripts $ cd scripts $ touch site.js
Теперь в твоем site.js
файл:
$(document).ready( function () { $('table').DataTable(); });
Что еще, вы сможете увидеть интерактивную таблицу на странице каталога.
Гитлаб Страницы
Создайте репозиторий Gitlab под вашим личным пространством или проектной группой. URL будет чем -то вроде https://gitlab.com/bername или имя группы проекта}/{repo name}
Анкет
Клонировать создание репо и создайте следующие элементы:
$ mkdir src $ touch .gitlab-ci.yml
Поместите свои элементы MKDOC (то есть Doc-Project
Папка) под SRC
Анкет Смотрите следующую структуру папки:
(root of the repo) ├── .gitlab-ci.yml └── src └── doc-project
.gitlab-ci.yml
.gitlab-ci.yml
является специфичным для Gitlab файл. Gitlab будет читать и запустить шаги в файле. Нам нужно сообщить Гитлабу, как генерировать и развернуть наш статический веб -сайт MKDOCS. В этом файле:
# In .gitlab-ci.yml... image: python:3.8-buster ## MkDocs requies python. pages: stage: deploy ## tell GitLab to deploy the website in this step. before_script: - pip install mkdocs ## install MkDocs. - pip install mkdocs-material ## install the theme. script: - cd ./src/doc-project - mkdocs build ## built the site. - mv site ../../public artifacts: paths: - public ## Uncomment the following section if you want to run this step under master branch only. # only: # - master
Таким образом, в основном он говорит Gitlab установить инструменты, необходимые в среде Python 3.8, и развернуть веб -сайт после создания сайта.
Попробуйте запустить следующую команду, если вы хотите создать сайт локально:
$ mkdocs build
Сгенерированный сайт расположен под doc-project/site/
Анкет
Чтобы правильно отобразить веб -сайт, вам необходимо разместить сгенерированный сайт под public
Папка и пусть Гитлаб знает Артефакт Внутри сайт, который вы хотите развернуть.
Стройте и разверните
Нажмите код в Gitlab, и сайт должен создавать автоматически. Проверьте статус сборки под CI/CD -> Трубопроводы Анкет
Зеленая метка, показывающая, прошел для каждого успешного строительства.
Проверьте свой сайт сейчас. URL https://{Имя пользователя или имя группы проекта} .gitlab.io/{repo name}/
.
Вывод
В этом уроке мы создали статический сайт с пользовательской темой, стилями и библиотекой JS с помощью MKDOCS. После этого мы установили трубопровод CI/CD на Gitlab для строительства и развертывания этого статического сайта на страницы Gitlab.
Оригинал: “https://dev.to/bemnlam/documentation-makes-easy-with-mkdocs-and-gitlab-pages-27e8”