IncludeShifted

IncludeShifted — это расширение для MediaWiki (совместимо с версиями 1.39+ и современным парсером Parsoid), которое позволяет строить сложные иерархические документы по принципу SGML/DocBook.

Расширение автоматически вычисляет контекст и сдвигает уровни заголовков во включаемых статьях (трансклюзиях) так, чтобы они логически вкладывались в родительский раздел.

Особенности архитектуры

• Стандартный синтаксис: Используется штатный механизм трансклюзий {{:Название_статьи}}. Никаких кастомных функций парсера, магических слов.
• Целостность базы данных: MediaWiki корректно записывает связи в таблицу templatelinks. Кнопка «Ссылки сюда» и отслеживание использования шаблонов работают безупречно. Совместимо с концепциями ссылок — то есть будет устойчиво к переименованиям включаемых статей, и можно отслеживать, кто включает и использует эту статью.
• Поддержка VisualEditor: Стандартные трансклюзии корректно отображаются и редактируются в визуальном редакторе.
• DOM-ориентированность: Сдвиг заголовков (тегов <hN> и классов mw-headingN для новых скинов) происходит на этапе генерации финального HTML, что позволяет обходить ограничения нового конвейера парсинга и избегать поломок при обработке сложного вики-текста.

Установка

1. Перенесите папку IncludeShifted в директорию extensions/ вашей установки MediaWiki.
2. Добавьте следующую строку в конец вашего файла LocalSettings.php:

   wfLoadExtension( 'IncludeShifted' );

Использование и режимы работы

Расширение поддерживает три уровня применения адаптивного сдвига заголовков.

1. Локальный режим (на уровне конкретного включения)

Для включения адаптивного сдвига только для одной трансклюзии, добавьте параметр shift_headings=1:

    == Основной раздел 2 уровня ==
    Какой-то текст...
    {{:Моя_подстатья|shift_headings=1}}

Если в Моя_подстатья есть заголовки == (2 уровня), они автоматически превратятся в === (3 уровень) при отображении в родительской статье.

2. Режим статьи (на уровне страницы)

Если в статье много трансклюзий, и вы хотите сделать их все адаптивными, используйте глобальный триггер для всей страницы:

• Добавьте в любое место страницы «магическое слово» __AUTOSHIFT__ или определите переменную (требуется установленное расширение Variables):

  {{#vardefine:auto_shift|1}}
  == Раздел А ==
  {{:Подстатья_1}}
  
  === Подраздел А.1 ===
  {{:Подстатья_2}}

В данном примере заголовки в Подстатья_1 сдвинутся относительно ==, а в Подстатья_2 вычислят контекст и сдвинутся относительно ===.

3. Глобальный режим (для всей Вики)

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

$wgAutoHeadShift = true;

(При включении этой настройки использовать параметры shift_headings или триггеры auto_shift в статьях больше не нужно).

---

Скрипт миграции старых тегов (<enableheadshift>)

Если ранее на вашей вики использовался устаревший пользовательский тег <enableheadshift> от патчей проекта MediaWiki4IntraNet, в расширение встроен maintenance-скрипт для бесшовной миграции базы данных.

Скрипт

• автоматически найдет все статьи с тегом <enableheadshift>,
• аккуратно удалит его
  • (опционально) проставит переменные auto_shift во все родительские статьи, которые ссылаются на данную.

Миграция выполняется от имени системного бота с правами sysop, сохраняя полную историю правок.

Запуск проверки без записи в базу (Dry Run):

    MW_INSTALL_PATH=/путь/к/mediawiki \
    php /путь/к/mediawiki/maintenance/run.php extensions/IncludeShifted/maintenance/migrateHeadShift.php --dry-run

Боевой запуск (Только очистка тегов): (Рекомендуется, если вы включили глобальную настройку $wgAutoHeadShift = true)

    MW_INSTALL_PATH=/путь/к/mediawiki \
    php /путь/к/mediawiki/maintenance/run.php extensions/IncludeShifted/maintenance/migrateHeadShift.php

Боевой запуск (С инъекцией локальных триггеров): (Рекомендуется, если глобальная настройка выключена. Скрипт добавит {{#vardefine:auto_shift|1}} во все включающие статьи)

    MW_INSTALL_PATH=/путь/к/mediawiki \
    php /путь/к/mediawiki/maintenance/run.php extensions/IncludeShifted/maintenance/migrateHeadShift.php --inject-triggers

Тестирование

Расширение покрыто интеграционными тестами PHPUnit для автоматической проверки логики математического сдвига и работы триггеров. Для запуска тестов используйте стандартный механизм из директории MediaWiki:

    php vendor/bin/phpunit extensions/IncludeShifted/tests/phpunit/IncludeShiftedTest.php

Архитектура «под капотом»

1. Хук ParserBeforeInternalParse обнаруживает триггеры и временно оборачивает конструкцию {{:Статья}} в уникальный HTML-блок (с сохранением \n для корректного парсинга внутренних блоков).
2. Парсер MediaWiki штатно обрабатывает шаблон, подгружает контент, строит кэш и регистрирует связи.
3. Хук ParserAfterParse в итоговом HTML находит наши обертки, регулярными выражениями сканирует предыдущий заголовок родителя, вычисляет математическую дельту и обновляет теги <hN> и классы mw-headingN внутри обертки. Затем обертка бесследно удаляется.