MediaWiki - Настройка и расширения: различия между версиями

Материал из Кафедра ИУ5 МГТУ им. Н.Э.Баумана, студенческое сообщество
Перейти к навигации Перейти к поиску
м (→‎BPoD: мелкий фэн-шуй)
м (→‎BPoD: и про пользователей)
 
Строка 11: Строка 11:
* некорректно работающее свежеустановленное расширение.
* некорректно работающее свежеустановленное расширение.


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


<code>error_reporting( -1 );
<code>error_reporting( -1 );
ini_set( 'display_errors', 1 );</code>
ini_set( 'display_errors', 1 );</code>
Потом это лучше убрать, чтобы пользователи не увидели лишнего.


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

Текущая версия от 13:01, 11 мая 2015

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

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

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

BPoD

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

  • неверные настройки в файле LocalSettings.php;
  • некорректно работающее свежеустановленное расширение.

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

error_reporting( -1 ); ini_set( 'display_errors', 1 );

Потом это лучше убрать, чтобы пользователи не увидели лишнего.

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

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

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

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

Настройка MediaWiki

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

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

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

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

$wgSitename = "Ваше название вики";

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

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

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

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

$wgLogo = "$wgStylePath/common/images/vashlogotip.gif";

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

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

Загружать иконку рекомундуется туда же, куда и логотип. Размеры её должны быть 16x16, а формат - ICO. Так же можно сделать ей прозрачный фон. Так же следует помнить, что после обновления MediaWiki она может сброситься на дефолтную.

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

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

$wgFavicon = "$wgStylePath/common/images/favicon.ico";

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

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

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

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

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

$wgEnableUploads = true;

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

$wgFileExtensions = array('png', 'gif', 'jpg', 'jpeg', 'svg');

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

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

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

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

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

$wgUseImageMagick = false;

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

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

По умолчанию у класса таблиц 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: 16px
}

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

Правка SyntaxHighlight_GeSHi.class.php

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

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

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

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

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

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

Использование 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 по тем именам, какими они сейчас отображаются.

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

&lt;changeemail&gt;

Значит, надо открыть страницу 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.

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

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

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

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