Настройка ikiwiki
Оглавление
Настройка внешнего вида
По умолчанию Ikiwiki выглядит довольно консервативно. К счастью, для настройки внешнего вида страниц не обязательно создавать собственную тему оформления с шаблонами страниц. Достаточно создать в каталоге с исходными файлами файл с дополнительными CSS-стилями - local.css. Например, я прописал в этот файл следующие стили:
body { margin-left: 10%; margin-right: 10%; background: url(https://stupin.su/blog/background.jpeg) repeat; }
table { border-collapse: collapse; margin: auto; }
td, th { border-style: solid; border-width: 1px; padding: 5px; }
pre code { background-color: black; color: white; display: inline-block; padding: 10px; }
blockquote { border-color: black; border-style: solid; border-left-width: 3px; border-right-width: 0px; border-top-width: 0px; border-bottom-width: 0px; padding-left: 5px; }
img { max-width: 100%; max-height: 480px; margin: auto; display: block; padding: 10px; }
Этот стиль:
- добавляет на страницу поля по 10 процентов слева и справа, а также фоновую картинку,
- выравнивает таблицы по середине текста, добавляет тонкие чёрные бордюры и слега отодвигает бордюры от содержимого ячеек,
- выводит фрагменты кода белыми буквами на чёрном фоне подходящей ширины,
- добавляет к цитатам слева вертикальную черту,
- выводит картинки по середине текста, ограничивает их размеры и добавляет отступы вокруг картинки.
После добавления стиля нужно как обычно выполнить обновление HTML-страниц, чтобы добавленный файл стилей появился в каталоге с HTML-страницами:
$ ikiwiki --setup src/.ikiwiki/ikiwiki.setup
Оформление страницы в целом и таблицы:
Оформление блока кода:
Оформление цитаты:
Плагины
Список плагинов, включенных по умолчанию, можно найти в исходном коде ikiwiki. В файле /usr/pkg/lib/perl5/vendor_perl/5.34.0/Ikiwiki.pm я нашёл следующий фрагмент кода:
default_plugins => {
type => "internal",
default => [qw{mdwn link inline meta htmlscrubber passwordauth
openid signinedit lockedit conditional
recentchanges parentlinks editpage
templatebody}],
description => "plugins to enable by default",
safe => 0,
rebuild => 1,
},
По умолчанию включены следующие плагины:
- mdwn
- link
- inline
- meta
- htmlscrubber
- passwordauth
- openid
- signinedit
- lockedit
- conditional
- recentchanges
- parentlinks
- editpage
- templatebody
Для подключения дополнительных плагинов нужно добавлять их к опции add_plugins в файле конфигурации. Я использую возможности YML для более наглядного форматирования списка следующим образом:
add_plugins:
- toc
- attachment
- websetup
- tag
websetup
Этот плагин позволяет редактировать файл конфигурации прямо через веб-браузер.
toc
Этот плагин добавляет поддержку директивы toc, с помощью которой можно добавить на страницу оглавление. У директивы есть две опции: startlevel и levels указывают минимальную и максимальную глубину заголовков в иерархии, которые будут добавлены в оглавление.
Например, чтобы исключить из оглавление заголовок первого уровня, которому соответствует HTML-тег h1, и не помещать в оглавление заголовки уровне 4-6, которым соответствуют HTML-теги h4-h6, можно использовать следующую директиву:
Результат можно увидеть на картинке:
attachments
Этот плагин позволяет добавлять к статьям вложенные файлы, например - картинки. Вложенные файлы загружаются в каталог, который называется так же, как и статья, к которой они относятся. Если в настройках включена опция indexpages, то исходный текст статьи и сам находится в этом же каталоге под именем index.
При включении плагина рядом с кнопками под окном редактирования страницы появляется дополнительная ссылка:
При нажатии на ссылку появляется список уже загруженных вложений и дополнительные кнопки:
remove
Этот плагин позволяет удалять файлы, к которым пользователь имеет доступ на редактирование.
Дополнительная кнопка под окном редактирования для удаления страниц:
rename
Этот плагин позволяет переименовывать файлы и страницы, к которым пользователь имеет доступ на редактирование. Кроме того, при переименовании пытается исправить все ссылки, указывающие на переименованный файл.
tag
Плагин позволяет проставлять у страниц метки и создавать для каждой метки страницу, на которой перечислены все статьи с этой меткой. У плагина есть несколько опций для его настройки:
tagbase- указывает каталог, в котором будут создаваться страницы меток, на которых будут перечислены все статьи с этой меткой,tag_autocreate- указывает, нужно ли автоматически создавать страницы меток,tag_autocreate_commit- указывает, нужно ли помещать страницы меток, созданные автоматически, в репозиторий системы управления версиями.
Я настроил плагин следующим образом:
tagbase: tag
tag_autocreate: 1
tag_autocreate_commit: 0
Страницы меток создаются автоматически в каталоге tag, но не помещаются в репозиторий системы упраления версиями. Я не редактирую страницы меток, созданные автоматически, поэтому мне нет смысла держать их в репозитории. Однако если вы захотите отредактировать страницы меток, например, прописав названия каждой статьи вместо её адреса, то стоит сохранять такие изменения в репозиторий и включить опцию tag_autocreate_commit.
После подключения плагина или изменения его настроек не забудьте применить настройки с помощью ранее упоминавшейся команды:
$ ikiwiki --setup src/.ikiwiki/ikiwiki.setup
Чтобы добавить метку на страницу, можно воспользоваться одной из двух директив, поддерживаемых плагином:
* tag - позволяет указать сразу несколько меток, статья попадёт на страницу метки, но все метки на самой станице будут невидимыми,
* taglink - позволяет указать только одну метку, но сама метка будет видимой и приобретёт вид ссылки, ведущей на страницу метки.
Примеры добавления меток:
[[!tag pkgsrc pkgsrc-wip]]
[[!taglink gitea]] [[!taglink mathopd]]
При использовании директивы taglink метки выглядят следующим образом:
Страница метки, сгенерированная автоматически, выглядит следующим образом:
pagestats
Этот плагин позволяет генерировать список страниц, соответствующих определённому критерию. Например, если составить список страниц из каталога tag, созданного с помощью одноимённого плагина, то получится список всех существующих меток. Для этого после включения плагина можно создать страницу, содержащую такую директиву:
[[!pagestats style="list" pages="tag/*"]]
Страница, сформированная таким образом, выглядит вот так:
Интеграция с git
Для интеграции ikiwiki с git-репозиторием нужно поместить исходный каталог в репозиторий git и настроить его для беспрепятственного выполнения команды git push.
Предположим, что путь к каталогу с исходными файлами - /home/wiki/src/. Тогда для настройки репозитория нужно выполнить следующие команды:
$ cd /home/wiki/src
$ git init
$ git config --local --add user.email wiki@stupin.su
$ git config --local --add user.name stupin.su/wiki
Добавим в репозиторий все файлы и сделаем первую фиксацию:
$ git add *
$ git commit -m "Начальное размещение файлов"
Для того, чтобы изменения отслеживались не только в локальном репозитории, но и в удалённом, нужно добавить ссылку на удалённый репозиторий, содержащий учётные данные пользователя для доступа по протоколу HTTP или HTTPS, либо настроить доступ к репозиторию по SSH с помощью SSH-ключа. Я воспользуюсь первым способом:
$ git remote add origin https://wiki:p4$$w0rd@stupin.su/git/stupin/wiki.git
В моём случае репозиторий размещается в системе Gitea. Gitea позволяет сгенерировать для пользователя ключ, который можно использовать вместо пароля. Именно его я и поместил в ссылку
Отправим локальные фиксации в ветку master репозитория origin:
$ git push -u origin master
Теперь можно включить в файле конфигурации src/.ikiwiki/ikiwiki.setup использование git:
rcs: 'git'
При помощи опции git_wrapper_background_command можно настроить команду для отправки изменений из локального репозитория в удалённый:
git_wrapper_background_command: 'git push'
Для применения настроек нужно вызвать ikiwiki с новым файлом конфигурации:
$ ikiwiki --setup src/.ikiwiki/ikiwiki.setup
Если всё хорошо, то изменения страниц должны фиксироваться в локальном и удалённом репозиториях. Под формой редактирования текста появится поле "Optional description of this change:" для ввода описания изменений, а в строке меню появится ссылка "RecentChanges", по которой можно будет отслеживать последние изменения:
Кроме того, можно указать опцию historyurl для добавления возможности просмотра изменений отдельной страницы. В моём случае репозиторий находится в Gitea и опция примет такой вид:
historyurl: 'https://stupin.su/git/stupin/wiki/commits/branch/master/[[file]]'
Имя страницы, историю изменения которой нужно посмотреть, будет подставляться вместо текста [[file]]. Для применения новых настроек нужно вызвать ikiwiki с новым файлом конфигурации:
$ ikiwiki --setup src/.ikiwiki/ikiwiki.setup
После этого в строке меню при просмотре страницы появится ссылка "History", ведущая в git-репозиторий с историей изменения файла текущей страницы. Выглядит это следующим образом:
Другие опции плагина можно найти в файле /usr/pkg/lib/perl5/vendor_perl/5.34.0/IkiWiki/Plugin/git.pm.