Привет, я занимался исследованиями и разработками для предстоящего проекта, которые кажутся относительно большими по сравнению с другими работами. Поэтому я искал инструмент подготовки документа, чтобы организовать все. Сначала Google Docs был хорошим вариантом, который был очень быстрым, простым в использовании и обслуживании. Но по мере увеличения содержания исследований становится все труднее отслеживать все точки. Поэтому я придумал MKDOCS, который кажется хорошим.
Давайте посмотрим, как настроить его в кратчайшие сроки.
Введение
- MKDOCS – это быстрый, простой и совершенно великолепный статический генератор сайтов, который ориентирован на создание документации проекта.
- Исходные файлы документации записаны в Markdown и настроены с одним файлом конфигурации YAML.
- Встроенный Dev-Server позволяет вам предварительно просмотреть вашу документацию, когда вы ее пишете. Он даже будет автоматически нагружаться и обновлять ваш браузер, когда вы сохраняете свои изменения.
Ручная установка
$ python --version Python 3.8.5 $ pip --version pip 20.3.3 from C:\Users\username\Anaconda3\lib\site-packages\pip (python 3.8)
pip install --upgrade pip
Установка MKDOCS
pip install mkdocs
$ mkdocs --version mkdocs, version 1.1.2
Начиная
mkdocs new demo cd demo
- Есть один файл конфигурации с именем mkdocs.yml и папка с именем DOCS, которая будет содержать ваши исходные файлы документации.
Прямо сейчас папка DOCS просто содержит одну страницу документации с именем index.md.
MKDOCS поставляется со встроенным Dev-Server, который позволяет вам предварительно просмотреть вашу документацию во время работы над ним.
Убедитесь, что вы находитесь в том же каталоге, что и файл конфигурации mkdocs.yml, а затем запустите сервер, запустив команду MKDOCS Serv:
$ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory [I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000 [I 160402 15:50:43 handlers:58] Start watching changes [I 160402 15:50:43 handlers:60] Start detecting changes
Откройте http://127.0.0.1:8000/ В вашем браузере, и вы увидите отображаемую домашнюю страницу по умолчанию:
Dev-Server также поддерживает автоматическую загрузку
Откройте документ docs/index.md в выборе текстового редактора, измените начальный заголовок на ваш выбор и сохраните ваши изменения
Теперь попробуйте редактировать файл конфигурации: mkdocs.yml. Измените настройку site_name на то, что вы всегда хотели просмотреть, и сохранить файл.
Добавление страниц
- Поскольку наш сайт документации будет включать некоторые заголовки для навигации, вы можете отредактировать файл конфигурации и добавить некоторую информацию о заказе, заголовке и гнездовании каждой страницы в заголовке навигации, добавив настройку NAV:
site_name: MkLorum
nav:
- Home: index.md
- About: about.md
- Сохраните свои изменения, и теперь вы увидите навигационную панель с домом и об элементах слева, а также поиск, предыдущие и следующие элементы справа.
Тематическая нашу документацию
- Теперь измените файл конфигурации, чтобы изменить то, как отображается документация, изменяя тему. Отредактируйте файл mkdocs.yml и добавьте настройку темы:
site_name: MkLorum
nav:
- Home: index.md
- About: about.md
theme: readthedocs
Построение сайта
- Это выглядит хорошо. Вы готовы развернуть первый проход вашей документации Mklorum. Сначала создайте документацию:
mkdocs build
- Это создаст новый каталог, названный сайт. Загляните в каталог:
$ ls site about fonts index.html license search.html css img js mkdocs sitemap.xml
- Обратите внимание, что ваша исходная документация была выведена как два файла HTML с именем index.html и о/index.html.
- У вас также есть различные другие средства массовой информации, которые были скопированы в каталоге сайта как часть темы документации.
У вас даже есть файл sitemap.xml и mkdocs/search_index.json.
Если вы используете элемент управления исходным кодом, такой как GIT, вы, вероятно, не хотите проверять сборку документации в репозиторий. * Добавьте строку, содержащую сайт/в ваш файл .gitignore.
Другие команды и параметры
mkdocs --help mkdocs build --help
Для получения дополнительной информации ознакомьтесь с официальными документами: Официальный сайт
Вот и все сейчас. Хаста Пронто! 🙌🙌
Оригинал: “https://dev.to/sandeepbalachandran/mkdocs-static-html-sites-and-documentation-preparation-tool-that-you-can-host-on-github-pages-262f”