MediaWiki - Настройка и расширения

Статья посвящена всему тому, с чем нам пришлось столкнуться в процессе использования MediaWiki. Такая своеобразная записная книжка.

Речь пойдёт об MediaWiki, размещённой на Linix-сервере. Подробнее о версиях установленного ПО можно узнать здесь.

Термины и сокращения

BPoD

Blanхкек дников и показать её самую последнюю версию. Так вы можете быть уверены, что перед вами не версия из кэша, а актуальная версия страницы.

Также это вызывает сиюминутную категоризацию страницы. Это полезно, когда категория страницы была изменена одним из используемых ей шаблонов, потому как сама вики в этом случае обновит категорию страницы лишь через некоторое время.

Настройка MediaWiki

В основном, вся проводится правкой файла LocalSettings.php. Он находится в ваввавава ===

По умолчанию у класса таблиц wikitable ничтожно маленькое значение отступа от границ ячейки, из-за чего таблицы не радуют глаз. Для установки собственного значения отступа необходимо внести изменения в файл skins\common\shared.css. Скажем, 5px будет достаточно:

table.wikitable {
	margin: 1em 1em 1em 0;
	background: #f9f9f9;
	border: 1px #aaa solid;
	border-collapse: collapse;
	color: black;
}
.wikitable th, .wikitable td {
	border: 1px #aaa solid;
	padding: 5px;
}

Если у вас другая версия MediaWiki, код класса может выглядеть иначе, но суть одна - нужно изменить значение параметра padding.

Установка счётчиков

Для установки счётчика надо включить его код в код каждой страницы вики, но вообще достаточно включить его лишь в код темы оформления (скина). Так как по умолчанию используется Vector, то рассмотрим на его примере.

Код счётчика лучше сохранить в файле с расширением .php и загрузить на сервер в каталог skins, после чего в файле темы оформления (Vector.php) надо будет включить в определённом месте имя этого файла. Не забывайте, что кодировка файла с кодом счётчика должна совпадать с кодировкой, используемой на вашем сайте, иначе вместо кириллицы будет отображаться кракозябра.

Счётчики могут отображать на странице свою пиктограммку с некоторыми данными, а могут не отображать. Но в обоих случаях они будут отправлять статистику посещений на свой сервер, где её можно будет подробно изучить.

Мы используем счётчик от Яндекса. Код его сохранён в файле skins/counter_yandex.php.

Для добавления счётчика редактируем файл skins/Vector.php:

<!-- footer -->
<div id="footer"<?php $this->html( 'userlangattributes' ) ?>>
<?php foreach( $this->getFooterLinks() as $category => $links ): ?>
	<ul id="footer-<?php echo $category ?>">
		<?php foreach( $links as $link ): ?>
			<li id="footer-<?php echo $category ?>-<?php echo $link ?>"><?php $this->html( $link ) ?></li>
		<?php endforeach; ?>
	</ul>
<?php endforeach; ?>
<?php $footericons = $this->getFooterIcons("icononly");
if ( count( $footericons ) > 0 ): ?>
	<ul id="footer-icons" class="noprint">
	<li><?php include("counter_yandex.php"); ?></li> <!-- включение счётчика Яндекса -->
<?php			foreach ( $footericons as $blockName => $footerIcons ): ?>
		<li id="footer-<?php echo htmlspecialchars( $blockName ); ?>ico">
<?php				foreach ( $footerIcons as $icon ): ?>
			<?php echo $this->getSkin()->makeFooterIcon( $icon ); ?>

<?php				endforeach; ?>
		</li>
<?php			endforeach; ?>
	</ul>
<?php endif; ?>
<div style="clear:both"></div>
</div>
<!-- /footer -->

После этого счётчик заработает, и должна стать видна его пиктограмма. Если же она не видна, то возможно её блокирует ваш браузер, его расширения или что-то ещё.

Расширения MediaWiki

Они же extensions. Позволяют расширить функционал вики. Например, добавить поддержку TeX формул и подсветку синтаксиса фрагментов исходного кода на том или ином языке программирования.

Устанавливаются все одинаково:

1. загрузить архив с расширением:
2. распаковать его в каталог extensions корневого каталога;
3. в файле LocalSettings.php из корневого каталога вики добавить строку подключения расширения.

Выполнить эти операции можно как по FTP, так и через SSH.

Подсветка синтаксиса

SyntaxHighlight GeSHi

У нас используется SyntaxHighlight GeSHi. Установка ничем не примечательна, однако на версии MediaWiki 1.17 расширение работать отказывалось - браузер выдавал лишь белую страницу смерти. Из-за этого до обновления приходилось использовать SyntaxHighlighter - более скромное расширение, поддерживающее гораздо меньше языков, зато работающее. Но сейчас всё в порядке.

Когда же после обновления MediaWIki удалось установить SyntaxHighlight GeSHi, то оказалось, что по умолчанию им используется довольно мелкий шрифт. По крайней мере, такое наблюдалось в Firefox, а Opera и IE отображали блоки кода с шрифтом нормальных размеров.

Правка MediaWiki:Geshi.css

Это не файл (в каталоге с расширением вы его не найдёте), а спецстраница вашей Вики: вашавики.net/index.php/MediaWiki:Geshi.css.

Изначально страница пустая, её необходимо создать. Всё, что здесь будет вноситься, будет дополнительно использоваться в стилях подсветки синтаксиса (расширение будет брать настройки отображения отсюда, в дополнение к своим).

Следующая конструкция управляет размером шрифта:

div.mw-geshi {
font-size: 15px
}

Однако, на нашей вики это эффекта не дало.

Правка SyntaxHighlight_GeSHi.class.php

Вот это уже действительно файл, который находится в каталоге самого расширения.

Нужно изменить строку:

$css[] = ".source-$lang {line-height: normal;}";

следующим образом (добавить запись про размер шрифта):

$css[] = ".source-$lang {line-height: normal; font-size: 12px;}";

После этого блоки с кодом стали отображаться удобочитаемыми и вообще радующими глаз.

Использование TeX формул

Так как мы технари, то нам просто необходима поддержка $$\TeX$$. Любые "псевдоформулы" набранные доступными с клавиатуры символами покрыли бы нас несмываемым позором. Потому за корректную работу расширения, обеспечивающего поддержку $$\TeX$$ разметки, нужно было бороться до конца.

Math

Начали мы с расширения Math. Тогда у нас стояла MediaWiki 1.17, и оно уже было включено в её состав. Располагалось оно не в обычном каталоге для расширений, а прямо в корневой директории сайта (каталог math).

Для работы расширения на сервере должны быть установлены пакеты latex и dvips. Если хостер отказывает в установке этих пакетов на сервере, то просите установить их в вашу домашнюю директорию, в ущерб выделенному вам на сервере дисковому пространству, или же меняйте хостера.

Итак, в каталоге с расширением лежат готовые к сборке исходники утилиты texvc. Нужно зайти в этот каталог и выполнить команду make. Однако, если вы проделываете это не на своём сервере (и прав на выполнение этой команды у вас нет), то об этом нужно попросить вашего хостера, обратившись в его техподдержку.

Затем создайте следующие каталоги и назначьте им права 755:

• images/math;
• images/tmp.

Далее необходимо задать следующие три переменных в файле настроек LocalSettings.php:

$wgUseTeX = "true"; 
$wgMathDirectory = "images/math";
$wgTmpDirectory = "images/tmp";

Также должна быть разрешена загрузка изображений.

После этого вики будет способна обрабатывать $$\TeX$$ формулы, заключённые в теге <math></math>. Вкратце обработка происходит следующим образом: latex обрабатывает формулу, заключённую в теге <math></math>, ImageMagic создаёт из этого картинку и помещает её на страницу. Таким образом, готовые формулы представляют собой растровые изображения.

Однако, простые формулы, вроде x + 2 = 4, вики по умолчанию отображает текстом, отчего они выглядят не как "картиночные". За это отвечает переменная в настройках внешнего вида вики для каждого зарегистрированного пользователя, но можно задать её по умолчанию для всех. Для этого надо изменить в LocalSettings.php следующую переменную:

$wgDefaultUserOptions['math'] = 0;

MathJax

После обновления MediaWiki до версии 1.19.2 расширение Math работать перестало. Восстановить его работу не удалось. Мы стали искать альтернативу и нашли не просто альтернативу, а прекрасное расширение MathJax.

Самым главным его отличием является то, что оно не использует (соответственно, и не требует) наличия на сервере пакетов latex и dvips, и итоговые формулы являются не растровыми изображениями, а векторными объектами, которые можно сколь угодно масштабировать без потери качества их отображения на странице.

Устанавливается расширение стандартно.

Для обработки формул помимо стандартного тега <math></math> можно (и удобнее) использовать родные символы $$ из $$\TeX$$.

Единственное что - формулы отображаются с тем размером шрифта, в окружении какого они используются, и потому выглядят довольно мелко. Эту проблему мы решили введением шаблона Формула. Идея в том, чтобы окружить формулу тегом увеличения размера шрифта:

<span style="font-size:130%">$x + 2 = 4$</span>

Сноски

Они же примечания. Для их создания используется расширение Cite. Пример использования сносок можно посмотреть в Песочнице.

Расширение устанавливается стандартно, и установилось оно без проблем. Однако, при попытке воспроизвести стандартный пример на странице вместо примечаний было лишь:

<cite_references_prefix> <cite_references_link_one> <cite_references_link_one> <cite_references_suffix>

То есть, какие-то действия производились, но результат был не тот, что должен был.

В итоге, всё решилось примерно так же, как и с недопереведёнными служебными страницами. Просто поочерёдно открывали одноимённые служебные страницы из пространства имён MediaWiki в Википедии и копировали текст оттуда на свои.

Обновление MediaWiki

Сам процесс подробнейше описан в официальной документации. Там же приводится несколько способов выполнения обновления. Обратите внимание на требования к ПО, особенно на версию PHP.

Мы же обновляем так:

1. загружаем архив с дистрибутивом отсюда;
2. распаковываем его в каталог с вики: tar xvzf mediawiki-1.20.2.tar.gz -C path/to/our/wiki/ --strip-components=1. С таким ключом распаковка пройдёт с заменой файлов, не трогая наши расширения, картинки и файл настроек;
3. идём в path/to/our/wiki/maintenance/ и выполняем там php5 update.php.

Всё, можно идти проверять версию MW.

Обновление с MediaWiki 1.17 до MediaWiki 1.19.2

Приведём сюрпризы, ожидавшие нас при обновлении с 1.17 до 1.19.2. Конечно, скорее всего, их бы не было, если бы мы тщательней изучили документацию перед обновлением.

Кстати, весьма вероятно, эти проблемы могут возникать не только при обновлении 1.17 до 1.19.2, но и при обновлении до других версий.

Логотип и иконка

Так как мы забыли, что размещённые по пути skins/common/images/ логотип и иконка сбросятся на дефолтные при обновлении, то они и сбросились. Пришлось заливать их обратно.

Запрет включения статей в категории шаблонов

Тег <noinclude>, препятствующий добавлению категории шаблона в статью, где он используется, перестал работать должным образом, и статьи с шаблонами моментально оказались в их категориях. Оказалось, что теперь "невключаемость" в категорию шаблона следует оформлять немного по-другому.

Как работало в 1.17:

<noinclude>[[Категория:Преподаватели]]</noinclude>

Как работает теперь в 1.19.2:

<noinclude>:[[Категория:Преподаватели]]</noinclude>

А через некоторое время стало работать и как раньше, потому мы вернули всё как было. Непонятно, что это случилось. Возможно, ненадолго сбилась категоризация, а после правок всё "перекатегоризировалось", так что, выходит, это двоеточие никак не влияло.

Выравнивание и таблицы

Конструкция, например, align="right" для выравнивая таблицы по правому краю страницы перестала обрабатываться, потому как за её обработку теперь вроде как отвечает CSS. В результате информационные таблицы, которые были удобно размещены справа, уехали влево.

Оказалось, что мы всё проспали: такой способ устарел и вообще считается плохой практикой в вёрстке. Вместо этого следует использовать следующее:

Для всей таблицы
Тип выравнивания	Код разметки
По левому краю	style="float:left;"
По правому краю	style="float:right;"
По центру	style="margin:auto;"
Для текста в ячейке
Тип выравнивания	Код разметки
По левому краю	style="text-align:left;"
По правому краю	style="text-align:right;"
По центру	style="text-align:center;"

Перевод некоторых служебных страниц

Слетел, (а скорее всего, в версии 1.19.2 просто отсутствует) перевод некоторых служебных страниц. Чтобы "доперевести" их, надо править страницы из пространства имён MediaWiki по тем именам, какими они сейчас отображаются.

Например, в служебных страницах висит уродливого вида ссылка:

<changeemail>

Значит, надо открыть страницу MediaWiki:Changeemail и внести в неё правку - написать перевод: "Изменить адрес электронной почты".

Для перевода надписей (подписей и иного текста), находящегося на этих страницах, править нужно эту же страницу в пространстве имён MediaWiki, но добавляя постфикс с именем надписи, под которым она сейчас отображается.

Например, на всё той же странице MediaWiki:Changeemail находится надпись с именем <changeemail-header>. Значит, надо открыть страницу MediaWiki:Changeemail-header и внести правку с переводом: "Изменение адреса электронной почты".

Важно учитывать регистр. Если переводимый элемент принадлежит, например, странице BlockList, то правку надо вносить не в MediaWiki:BlockList, а в MediaWiki:Blocklist.

Обновление с MediaWiki 1.19.2 до MediaWiki 1.20.2

Выполнив всё по инструкции мы получили Fatal exception of type MWException при открытии любой страницы сайта.

Решение было найдено на доске поддержки MediaWiki. В итоге, обновление прошло следующим образом:

1. загружаем архив с дистрибутивом отсюда;
2. распаковываем его в каталог с вики: tar xvzf mediawiki-1.20.2.tar.gz -C path/to/our/wiki/ --strip-components=1. С таким ключом распаковка пройдёт с заменой файлов, не трогая наши расширения, картинки и файл настроек;
3. идём в path/to/our/wiki/maintenance/ и выполняем там: php5 update.php.
4. здесь же выполняем: php5 rebuildLocalisationCache.php --force.

не Важные мелочи

Небольшие, но важные советы:

• при создании шаблонов ни в коем случае не оставляйте пустых строк сверху (и снизу) конструкции <noinclude>. В противном случае пустая строка перенесётся в статью вместе с шаблоном и устроит там содомию.