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

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

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

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

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

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

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

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

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

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

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

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

Конвертация 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 конвертации - в "Ссылках" ниже.

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

Подстраницы

Иерархию страниц можно организовать не только с помощью категорий, но и с помощью функционала подстраниц.

Правила простые - создавайте новую статью в качестве подстраницы имеющейся статьи путем написания заголовка новой статьи через слеш после заголовка родителя в URL. Поначалу вы ничего особенного не почувствуете. Но стоит в источнике родительской статьи прописать:

  {{Special:PrefixIndex/{{FULLPAGENAME}}/}}

как на месте данного кода возникнет список всех подстраниц текущей страницы.

Это еще не всё. Если в файле LocalSettings.php прописать:

  $wgNamespacesWithSubpages[NS_MAIN] = true;

то на дочерней подстранице вверху появится ссылка на родительскую страницу.

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

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

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

Выводы

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

Ссылки

• Описание механизма Шаблонов MediaWiki
• Настройка загрузки файлов
• Расширения для MediaWiki
• Расширение EmbedVideo
• Расширения для конвертации wiki-страниц в PDF
• Использование MediaWiki для создания корпоративной базы знаний