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

2014-04-09T10:10:09Z

195.91.152.254: /* Обновление с MediaWiki 1.19.2 до MediaWiki 1.20.2 */

Статья посвящена всему тому, с чем нам пришлось столкнуться в процессе использования [http://www.mediawiki.org/ MediaWiki]. Такая своеобразная записная книжка.

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

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

=== BPoD ===

Blank Page of Death (BPoD) - белая страница смерти, когда вместо страницы вики браузер выдаёт лишь пустую страницу, на которой нет вообще ничего. Причиной может быть:
* неверные настройки в файле <code>LocalSettings.php</code>;
* некорректно работающее свежеустановленное расширение.

=== Нулевая правка ===

Null edit - это если зайти в режим ''Правки'' страницы и тут же нажать ''Записать страницу'' (''Save page''), хотя изменений никаких внесено не было. Как бы ни казалось на первый взгляд, но это вовсе не бессмысленное действие.

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

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

== Настройка MediaWiki ==

В основном, вся проводится правкой файла <code>LocalSettings.php</code>. Он находится в корневой директории сайта.

=== Первичная настройка ===

==== Задание названия ====

В файле <code>LocalSettings.php</code> задать переменную:

<syntaxhighlight lang="php">$wgSitename = "Ваше название вики";</syntaxhighlight>

==== Установка логотипа ====

Логотип можно загрузить через интерфейс самой вики, но тогда он окажется доступным для изменения, потому лучше положить его в каталог к дефолтному: <code>skins/common/images/</code>. Однако, тогда при обновлении MediaWiki логотип сбросится вновь на дефолтный или вовсе не будет отображаться.

Логотип должен быть квадратным, с размерами 135x135. Чтобы он смотрелся аккуратно и не выделялся своим фоном на фоне страниц вики, нужно [[Прозрачный фон изображения | сделать ему прозрачный фон]].

После того, как логотип загружен на сервер, нужно задать следующую переменную в файле <code>LocalSettings.php</code>:

<syntaxhighlight lang="php">$wgLogo = "$wgStylePath/common/images/vashlogotip.gif";</syntaxhighlight>

==== Установка иконки ====

Иконка сайта отображается на вкладке браузера, благодаря чему его (сайт) проще отыскать в массе открытых вкладок.

Загружать иконку рекомундуется туда же, куда и [[#Установка логотипа | логотип]]. Размеры её должны быть 16x16, а формат - {{Википедия|ICO_(формат_файлов)|ICO}}. Так же можно [[Прозрачный фон изображения | сделать ей прозрачный фон]]. Так же следует помнить, что после обновления MediaWiki она может сброситься на дефолтную.

Имя рекомендуется использовать стандартное: <code>favicon.ico</code>.

После того, как иконка загружена на сервер, нужно задать следующую переменную в файле <code>LocalSettings.php</code>:

<syntaxhighlight lang="php">$wgFavicon = "$wgStylePath/common/images/favicon.ico";</syntaxhighlight>

==== Изменение навигационного блока ====

Навигационный блок, расположенный на левой части каждой страницы вики, можно изменять: удалять существующие пункты, добавлять свои. Делается это на спецстранице <code>вашавики.net/index.php/MediaWiki:Sidebar</code>

=== Разрешение загрузки изображений ===

Чтобы пользователи могли загружать изображения, а также для работы некоторых расширений необходимо внести в <code>LocalSettings.php</code> следующие изменения:

Разрешить загрузку файлов на сервер:

<syntaxhighlight lang="php">$wgEnableUploads = true;</syntaxhighlight>

Установить разрешённые расширения файлов:

<syntaxhighlight lang="php">$wgFileExtensions = array('png', 'gif', 'jpg', 'jpeg', 'svg');</syntaxhighlight>

Также для работы некоторых расширений может потребоваться редактор изображений ImageMagick:

<syntaxhighlight lang="php">
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert"; # у вас может находиться в иной директории
</syntaxhighlight>

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

Ошибка создания миниатюры: public_html/bin/ulimit4.sh: line 4: /usr/bin/convert: Permission denied

В этом случае помогает отключение использования ImageMagick:

<syntaxhighlight lang="php">
$wgUseImageMagick = false;
</syntaxhighlight>

Вы спросите, а что делать, если возникли проблемы с миниатюрами, но ImageMagick необходим для работы расширения? И мы не ответим на этот вопрос.

=== Изменение стиля wikitable ===

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

<syntaxhighlight lang="php" highlight="10">
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;
}
</syntaxhighlight>

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

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

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

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

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

Мы используем счётчик от [http://metrika.yandex.ru/add/ Яндекса]. Код его сохранён в файле <code>skins/counter_yandex.php</code>.

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

<syntaxhighlight line enclose="div" highlight="13" lang=php>

<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>

</syntaxhighlight>

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

== Расширения MediaWiki ==

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

Устанавливаются все одинаково:
# загрузить архив с расширением:
# распаковать его в каталог <code>extensions</code> корневого каталога;
# в файле <code>LocalSettings.php</code> из корневого каталога вики добавить строку подключения расширения.

Выполнить эти операции можно как по FTP, так и [[Работа с Linux-сервером | через SSH]].

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

==== SyntaxHighlight GeSHi ====

У нас используется [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi SyntaxHighlight GeSHi]. Установка [[#Расширения MediaWiki | ничем не примечательна]], однако на версии MediaWiki 1.17 расширение работать отказывалось - браузер выдавал лишь [[#BPoD | белую страницу смерти]]. Из-за этого до обновления приходилось использовать [http://www.mediawiki.org/wiki/Extension:SyntaxHighlighter SyntaxHighlighter] - более скромное расширение, поддерживающее гораздо меньше языков, зато работающее. Но сейчас всё в порядке.

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

===== Правка MediaWiki:Geshi.css =====

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

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

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

<syntaxhighlight lang="css">div.mw-geshi {
font-size: 16px
}</syntaxhighlight>

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

===== Правка SyntaxHighlight_GeSHi.class.php =====

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

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

<syntaxhighlight lang=php>$css[] = ".source-$lang {line-height: normal;}";</syntaxhighlight>

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

<syntaxhighlight lang=php>$css[] = ".source-$lang {line-height: normal; font-size: 16px;}";</syntaxhighlight>

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

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

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

==== Math ====

Начали мы с расширения [http://www.mediawiki.org/wiki/Extension:Math Math]. Тогда у нас стояла MediaWiki 1.17, и оно уже было включено в её состав. Располагалось оно не в обычном каталоге для расширений, а прямо в корневой директории сайта (каталог <code>math</code>).

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

Итак, в каталоге с расширением лежат готовые к сборке исходники утилиты <code>texvc</code>. Нужно [[Работа с Linux-сервером | зайти в этот каталог и выполнить команду]] <code>make</code>. Однако, если вы проделываете это не на своём сервере (и прав на выполнение этой команды у вас нет), то об этом нужно попросить вашего хостера, обратившись в его техподдержку.

Затем создайте следующие каталоги и [[Работа с Linux-сервером | назначьте им права 755]]:
* <code>images/math</code>;
* <code>images/tmp</code>.

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

<syntaxhighlight lang=php>$wgUseTeX = "true";
$wgMathDirectory = "images/math";
$wgTmpDirectory = "images/tmp";</syntaxhighlight>

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

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

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

<syntaxhighlight lang=php>$wgDefaultUserOptions['math'] = 0;</syntaxhighlight>

==== MathJax ====

После обновления MediaWiki до версии 1.19.2 расширение [http://www.mediawiki.org/wiki/Extension:Math Math] работать перестало. Восстановить его работу не удалось. Мы стали искать альтернативу и нашли не просто альтернативу, а прекрасное расширение [http://www.mediawiki.org/wiki/Extension:MathJax MathJax].

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

Устанавливается расширение [[#Расширения MediaWiki | стандартно]].

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

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

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

=== Сноски ===

Они же ''примечания''. Для их создания используется расширение [https://www.mediawiki.org/wiki/Extension:Cite Cite]. Пример использования сносок можно посмотреть в [[Песочница#Сноски | Песочнице]].

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

<code><nowiki><cite_references_prefix> <cite_references_link_one> <cite_references_link_one> <cite_references_suffix></nowiki></code>

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

В итоге, всё решилось примерно так же, как и с [[#Перевод некоторых служебных страниц | недопереведёнными служебными страницами]]. Просто поочерёдно открывали одноимённые служебные страницы из пространства имён <code>MediaWiki</code> в Википедии и копировали текст оттуда на свои.

== Обновление MediaWiki ==

Сам процесс [http://www.mediawiki.org/wiki/Manual:Upgrading подробнейше описан] в официальной документации. Там же приводится несколько способов выполнения обновления. Обратите внимание на требования к ПО, особенно на версию PHP.

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

Всё, можно идти проверять [[Special:Version | версию MW]].

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

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

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

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

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

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

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

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

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

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

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

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

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

{| class="wikitable"
|- align="center"
! colspan="2" | Для всей таблицы
|- align="center"
! Тип выравнивания !! Код разметки
|- align="center"
| По левому краю || <code>style="float:left;"</code>
|- align="center"
| По правому краю || <code>style="float:right;"</code>
|- align="center"
| По центру || <code>style="margin:auto;"</code>
|- align="center"
! colspan="2" | Для текста в ячейке
|- align="center"
! Тип выравнивания !! Код разметки
|- align="center"
| По левому краю || <code>style="text-align:left;"</code>
|- align="center"
| По правому краю || <code>style="text-align:right;"</code>
|- align="center"
| По центру || <code>style="text-align:center;"</code>
|}

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

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

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

<syntaxhighlight lang="sql"><changeemail></syntaxhighlight>

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

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

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

Важно учитывать регистр. Если переводимый элемент принадлежит, например, странице <code>BlockList</code>, то правку надо вносить не в <code>MediaWiki:Block<span style="color:red">'''L'''</span>ist</code>, а в <code>MediaWiki:Block<span style="color:green">'''l'''</span>ist</code>.

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

Выполнив всё по [[#Обновление MediaWiki | инструкции]] мы получили <font color="red">'''Fatal exception of type MWException'''</font> при открытии любой страницы сайта.

Решение было найдено на [http://mediawiki.org/wiki/Project:Support_desk доске поддержки MediaWiki]. В итоге, обновление прошло следующим образом:
# загружаем архив с дистрибутивом [http://www.mediawiki.org/wiki/Download отсюда];
# распаковываем его в каталог с вики: <code>tar xvzf mediawiki-1.20.2.tar.gz -C path/to/our/wiki/ --strip-components=1</code>. С таким ключом распаковка пройдёт с заменой файлов, не трогая наши расширения, картинки и файл настроек;
# идём в <code>path/to/our/wiki/maintenance/</code> и выполняем там: <code>php5 update.php</code>.
# здесь же выполняем: <code>php5 rebuildLocalisationCache.php --force</code>.

Так же данная ошибка может возникнуть при переносе mediawiki между системами. В таком случае необходимо убедиться, что стоит расширение APC от PHP.

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

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

[[Категория:MediaWiki]]

Кафедра ИУ5 МГТУ им. Н.Э.Баумана, студенческое сообщество - Вклад [ru]

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