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

1. Изменение структуры бокового меню

Структуру сайдбара (боковое меню слева на страницах wiki-сайтов) можно менять на странице MediaWiki:Sidebar – просто править ее в wiki-редакторе, придерживаясь синтаксиса:

  * <название блока 1>
  ** <ссылка 1>|<отображаемый текст 1>
  ** <ссылка 2>|<отображаемый текст 2>

Эта страница требует прав на изменение. Чтобы в сайдбар поместить древовидный каталог надо подключить расширение CustomNavBlocks. Сайдбар надо будет изменить под структуру хранимой документации. Теоретически в сайдбар можно было бы внедрять и оглавление отдельного документа (как в Word в панели навигации). Но делать этого не стоит, т.к., во-первых, это оглавление будет видно в сайдбаре всегда, даже, когда пользователь находится на другой странице, во-вторых, на отдельной странице документа содержание и так выводится сверху согласно оформленных заголовков.

2. Загрузка файлов различных форматов

По умолчанию в виде файлов можно загружать только png, gif, jpg, jpeg, webp. Список возможных расширений можно расширить в файле LocalSettings.php в строке:

  $wgFileExtensions = [ 'png', 'gif', 'jpg', 'jpeg', 'webp' ];

Нужен админский доступ к этому файлу. Для ведения документации в Wiki мне лично не хватает загрузки по крайней мере файлов с такими расширениями: docx, pdf, svg, bpmn, zip.

3. Использование принципа единого источника

Этот принцип практикуется в «продвинутых» относительно Word технологиях создания документации (DocBook, DITA...) и заключается в том, что повторяющийся один и тот же блок данных (тест, картинки...) хранится в одном(!) месте и подтягивается в разные документы спецкомандами.
MediaWiki имеет функционал шаблонов, который поддерживает данный принцип.
Создается страница, например, Шаблон:Todo. Потом в разных статьях в редакторе пишется {{Todo}} и в это место при отображении в браузере Wiki вставляет содержимое вышеприведенной страницы.
В шаблонах можно задавать места для параметров, например {{{par}}}, а при вызове параметру присваивать значение, например, {{Todo|par=Абракадабра}}. Такие плейхолдеры полезны для другой отличительной особенности «продвинутых» технологий – когда требуются минорные изменения шаблона на лету в зависимости от того, в какой документ вставляется шаблон.
Специального доступа к шаблонам в Wiki не требуется.
Можно вставить в страницу_1 содержание страницы_2 и без шаблонов: {{:страница_2}}.

4. Подсветка синтаксиса программного кода

Есть варианты:

1. SyntaxHighlight – расширение для MediaWiki, которое нужно подключить.
2. HIGHLIGHT.JS – библиотека JS+CSS для подсветки кода различных языков. Подключается ссылками на js и css файлы (или на cdn сервере, или на скачанные). Есть неплохая подсветка XML. Выбор стилей подсветки. Чтобы разместить js, css на сервере (в виде файла или в БД) нашей Wiki и включить их в шапку страниц Wiki требуется администратор.

5. Конвертация wiki-разметки

Word ➞ Wiki (варианты):

1. Есть некоторое расширение Word2MediaWikiPlus.
2. Экспортировать из Word файл docx в mht (вебстраница в одном файле). Потом открыть в браузере и скопировать в буфер обмена. Потом вставить в новую страницу Wiki в визуальном редакторе. Картинки при этом надо будет загрузить и прописать отдельно. Примечания также оформить отдельно.
3. В Word выделить текст и скопировать в буфер обмена. В визуальном редакторе Wiki вставить из буфера. Результат есть, но придется с форматированием чуть больше повозиться.

Excel ➞ Wiki:

   Сохранить лист книги в веб-страницу mht. Открыть в браузере. Выделить всё (Ctrl+A). Скопировать в буфер обмена. В визуальном редакторе Wiki вставить из буфера.

Wiki ➞ Word (варианты):

1. Расширение DocExport позволяет выкачать любую страницу вики в формате MS Word.
2. Скопировать из Wiki в буфер обмена и вставить в Word.

Wiki ➞ PDF:

   Это реально. В той же Википедии в сайдбаре каждой статьи есть ссылка "Скачать как PDF". Вполне нормально и быстро конвертирует за исключением того, что отсутствуют закладки согласно заголовкам. Страница проекта по PDF конвертации - в "Ссылках" ниже.

6. Другие полезные фичи MediaWiki

Категоризация статей

Чрезвычайно полезная функция, которая позволяет маркировать статьи и загруженные файлы по темам. Для этого достаточно внизу статьи добавить строку [[Категория:Название_категории]]. Если статья принадлежит разным категориям, то маркировку для каждой категории нужно повторить.
В результате таких маркировок, во-первых, в Wiki будет существовать страница Категория:Название_категории со списком статей и файлов данной категории, во-вторых, на странице Служебная:Категории будет ссылка на категорию Название_категории. Данные служебные страницы по мере маркировок новых статей будут актуализироваться автоматически.
Возможна иерархия категорий, если страницу дочерней категории пометить кодом родительской категории.
Функция категоризации в совокупности с функцией загрузки и хранения файлов разных форматов позволяет с удобствами использовать движок в качестве хранилища документации.

Просмотр загруженных файлов по формату

Есть служебная страница Служебная:MediaStatistics. На ней аггрегируется статистика по количеству файлов определенного формата, загруженных в Wiki. Название формата в списке - это активная ссылка, которая ведет на страницу со списком файлов определенного формата. Если загружать файлы документации только в форматах PDF и DOCX, то это будет дополнительным удобным местом для знакомства с наполнением Wiki, которое касается документации. Если загружать схемы только в формате BPMN, то на этой странице их также будет удобно искать.
Если маркировать страницы загруженных файлов категорией, то на странице этой категории будет существовать обособленный раздел "Файлы в категории", что крайне полезно для нашей заявленной задачи.
Эта фича в совокупности с возможностью расширять список загружаемых форматов также является сильной стороной движка в использовании его в качестве файлового хранилища.

Сноски

Предустановленное расширение Cite позволит пользователю Wiki с удобством расставлять сноски по тексту, что особенно актуально и полезно в научных статьях, но также может пригодиться и в технической документации. Расширение хоть и поставляется с движком, находясь в папке extensions, но не активизировано в файле LocalSettings.php. Поэтому, в этом файле надо прописать:

wfLoadExtension( 'Cite' );

После этого в тексте в тех местах, откуда надо сослаться на источник/комментарий/примечание надо в коде страницы вставить <ref>Пояснение = текст сноски</ref>, а в конце страницы сделать вывод всех этих примечаний примерно так:

== Примечания ==
<references/>

В итоге в месте ссылки на сноску она будет выглядеть так: [2] и это будет кликабельная ссылка, которая будет перебрасывать читателя вниз в раздел Примечания и текст нужной сноски будет подсвечен. Тексты сносок в разделе Примечания будут также ссылками, ведущими на место сноски в тексте.

Подключать свои JS и CSS файлы

Это можно делать двумя глобальными способами:
1. Писать свой код на страницах MediaWiki:Common.js и MediaWiki:Common.css
2. Подключать js-скрипты и css-стили файлы в LocalSettings.php:

$wgHooks['BeforePageDisplay'][] ='onBeforePageDisplay';
function onBeforePageDisplay( OutputPage &$out, Skin &$skin )
{ # подключаем нужное в конец head
    $script = '
	<link rel="stylesheet" href="/resources/lib/hightlight-js/styles/solarized-dark.css">
	<script type="text/javascript" src="/resources/lib/hightlight-js/highlight.min.js"></script>
	<script>hljs.initHighlightingOnLoad();</script>
	';
    $out->addHeadItem("itemName", $script);
    return true;
};

В первом случае js и/или css код будет хранится в базе данных и из нее подтягиваться на каждую страницу. Во втором случае содержание переменной $string будет внедряться в область заголовка <head> каждой страницы.
Также для кастомизированных css-стилей есть расширение CSS (ссылка ниже), благодаря которому можно будет подключать css как для всех страниц Wiki, так и для отдельных.

Возможность вставлять на страницы видео- и аудио-ролики

Подключить расширение EmbedVideo. Оно устанавливается без всяких сложностей в три этапа:

1. Скачать архив с расширением;
2. Скопировать содержимое архива в папку /extensions и переименовать внутриархивную папку в EmbedVideo;
3. В файле LocalSettings.php прописать wfLoadExtension( 'EmbedVideo' );.

После этого форматы медиафайлов, прописанные в EmbedVideo.hooks.php, становятся разрешенными для загрузки в Wiki. И начинают действовать обработчики плейсхолдеров в коде wiki-страниц для вставки видео и аудио. Самый простой плейсхолдер: [[File:S1200.mp4]] вставляет видеоролик, который был загружен на сервер.

Кроме видеороликов, загруженных в локальную Wiki, расширение позволяет вставлять на страницу iframe с src на адрес видеоролика одного из популярных сервисов с помощью разнообразных плейсхолдеров. Доступные сервисы можно найти в файле VideoService.php и, по всей видимости, добавить свой сервис можно там же при достаточном знании PHP и регулярных выражений.

Поиск

На каждой странице Wiki вверху справа есть поле для поиска, которое удовлетворит 80% ваших запросов. Но в некоторых случаях этого недостаточно.

Пример: Нам надо найти все статьи, где встречается слово "рыбалка".
Если поиск делать через верхнее правое поле на какой-нибудь странице, то результатом поиска будет открытие статьи с заголовком "Рыбалка", т.к. поисковое слово полностью совпадает с названием статьи.
Если же поиск делать со страницы Расширенного поиска Служебная:Поиск, то результатом поиска будут разные статьи – и в названиях которых, и в тексте которых встречается искомое слово, что правильней.

Также в интерфейсе Расширенного поиска можно выбрать пространство имен, по которому производится поиск. Например, можно отметить галочку "Файл" для того, чтобы поиск производился по страницам загруженных файлов (поиск по названиям файлов и тексту, который разместил пользователь на странице файла).

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

7. Выводы

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

Оригинал статьи здесь (это мой оригинал).