Начало работы

Установка

Material for MkDocs опубликован как Python пакет и может быть установлен с помощью pip. Откройте терминал и установите пакет с помощью:

pip install mkdocs-material

Вместе с пакетом установятся необходимые версии его зависимостей: MkDocs, Markdown, Pygments и Python Markdown Extensions.

Создание сайта

Чтобы создать базу документации, перейдите в нужную директорию и выполните следующую команду в терминале:

mkdocs new .

Она создаст следующую структуру:

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

mkdocs.yml — основной файл документации, в нём хранятся все настройки и маршруты, и все команды, связанные с созданным сайтом нужно выполнять в директории, в которой находится этот файл.
docs/ — директория, в которой хранятся все файлы сайта: дополнительные стили, картинки, файлы Markdown.

Предварительный просмотр

В MkDocs есть возможность запустить локальный сервер для предварительного просмотра. Все изменения тут же отражаются на сайте. Чтобы его запустить, перейдите в директорию с файлом mkdocs.yml и выполните команду:

mkdocs serve

Затем перейдите на http://localhost:8000, и вы увидите следующую страницу:

Выглядит не очень, не правда ли? Чтобы это исправить, необходимо настроить файл конфигурации, об этом в следующем разделе.