mkdocs.yml
Привет!
Сегодня мы настроим конфиг нашего сайта — mkdocs.yml
В нашем проекте уже есть этот файл, и пока что он состоит только из одной записи:
site_name: Parawriter docs
Остальные настройки добавляются аналогично в формате ключ: значение.
Что мы можем и должны прописать в конфиге?
Во-первых, все настройки самого сайта: параметры используемой темы, меню сайта, язык, расширения маркдауна.
Во-вторых, все страницы сайта: в доку попадут только те файлы, которые записаны в конфиг, и только в том порядке, в котором они записаны.
Я долго думал, как уместить в один пост всё многообразие настроек сайта. И придумал:
Я подготовил шаблон конфига с самыми используемыми настройками. Каждому параметру дан поясняющий комментарий. Некоторые настройки отключены: для их включения просто удалите символ # в начале нужной строки. Чтобы отключить какую-нибудь активную настройку, наоборот, добавьте символ # в начало нужной строки.
Вы можете поиграться с параметрами, включая и отключая их и проверяя результат в локальной сборке.
Также в конфиг добавлены файлы из дефолтной схемы доки, которую мы обсуждали в прошлый раз. Если вы разработали свою структуру сайта, смело правьте раздел nav в конфиге, только будьте внимательны и следите за отступами и вложенностью страниц.
Подробное описание настроек конфига можно посмотреть тут.
Итак:
1. Скачайте конфиг из этого поста;
2. Добавьте его в свой проект (удалив при этом старый конфиг);
3. Настройте на свой вкус;
4. Приведите настройки nav в соответствие со своей структурой. Убедитесь, что все md-файлы проекта добавлены в конфиг;
5. Соберите доку локально с помощью команды mkdocs serve и убедитесь, что всё работает;
6. Отправьте изменения на сервер (не забываем, что все эти действия нужно производить в новой рабочей ветке по нашему git-флоу)
Поздравляю! Наш проект теперь почти готов!
В следующий раз мы займёмся, наверное, самым сложным — настройкой публикации сайта на github pages.
А если вы столкнулись с трудностями — добро пожаловать в комментарии!
P.S. Друзья! Если вы используете предложенную мной структуру про озера и реки, обратите внимание на изменения структурной схемы в прошлом посте.
#docsascode #практика
Сегодня мы настроим конфиг нашего сайта — mkdocs.yml
В нашем проекте уже есть этот файл, и пока что он состоит только из одной записи:
site_name: Parawriter docs
Остальные настройки добавляются аналогично в формате ключ: значение.
Что мы можем и должны прописать в конфиге?
Во-первых, все настройки самого сайта: параметры используемой темы, меню сайта, язык, расширения маркдауна.
Во-вторых, все страницы сайта: в доку попадут только те файлы, которые записаны в конфиг, и только в том порядке, в котором они записаны.
Я долго думал, как уместить в один пост всё многообразие настроек сайта. И придумал:
Я подготовил шаблон конфига с самыми используемыми настройками. Каждому параметру дан поясняющий комментарий. Некоторые настройки отключены: для их включения просто удалите символ # в начале нужной строки. Чтобы отключить какую-нибудь активную настройку, наоборот, добавьте символ # в начало нужной строки.
Вы можете поиграться с параметрами, включая и отключая их и проверяя результат в локальной сборке.
Также в конфиг добавлены файлы из дефолтной схемы доки, которую мы обсуждали в прошлый раз. Если вы разработали свою структуру сайта, смело правьте раздел nav в конфиге, только будьте внимательны и следите за отступами и вложенностью страниц.
Подробное описание настроек конфига можно посмотреть тут.
Итак:
1. Скачайте конфиг из этого поста;
2. Добавьте его в свой проект (удалив при этом старый конфиг);
3. Настройте на свой вкус;
4. Приведите настройки nav в соответствие со своей структурой. Убедитесь, что все md-файлы проекта добавлены в конфиг;
5. Соберите доку локально с помощью команды mkdocs serve и убедитесь, что всё работает;
6. Отправьте изменения на сервер (не забываем, что все эти действия нужно производить в новой рабочей ветке по нашему git-флоу)
Поздравляю! Наш проект теперь почти готов!
В следующий раз мы займёмся, наверное, самым сложным — настройкой публикации сайта на github pages.
А если вы столкнулись с трудностями — добро пожаловать в комментарии!
P.S. Друзья! Если вы используете предложенную мной структуру про озера и реки, обратите внимание на изменения структурной схемы в прошлом посте.
#docsascode #практика