Оглавление страницы

Плагины

mdbook имеет много плагинов, которые расширяют возможности сайта. Список некоторых плагинов есть на их вики.

Вообще всё это называется preprocessor. По сути программа, которая будет запущена до сборки проекта. Я не особо знаю в какой момент это происходит, но кажется это не особо важно. Мне кажется, скрипты запускаются до сборки, тупо в директории проекта. Подробнее про работу и написание своего препроцессора можно почитать в их доке.

pagetoc

Давайте вернёмся к теме статьи. Подробное оглавление статьи является очень полезным, особенно в больших статьях, хотя мы и пытаемся писать всё кратко в одном файле. Самые известные проекты с оглавлением это книги или википедия.

На вике mdbook есть проект mdBook-pagetoc. Посмотрите примеры на тестовом сайте. Действительно красиво, там даже issues в mdbook сделан. В общем автор просто написал скрипт на js, который настолько простой, что можно его было и самому написать. Но если работает, не трожь, поэтому попробуем запустить проект.

Интеграция в проект

Добавим в book.toml строки для новых js и css. Создадим папку theme и сделаем некоторый файл index.hbs, который поход на html.

Вообще Handlebars (bhs) это очень старинный (я просто не разбираюсь в истории проктов) шаблонизатор на js.

Потом я ввёл в гугл что-то по типу mdbook index.hbs и даже нашёл сделал поиск по названию файла в репозитории, и в действительности это до сих пор используется. Чтобы использовать последнюю версию index.hbs я просто сделал сравнение между последней версией index.hbs и версией в плагине . Единственное существенное отличие заключается только в блоке кода который начинается на <div id="content" class="content">, в нём стоит добавить

<!-- Page table of contents -->
<div class="sidetoc"><nav class="pagetoc"></nav></div>

Осталось запустить проект и получить желанное оглавление с последней версией!!

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