Вас приветствует Mitrotsky. В данном руководстве вы научитесь создавать собственные статьи с оффсетами — дополнительными страницами в рамках одной статьи. Если у вас есть базовое понимание работы сайта, то можете сразу перейти к пункту «Быстрый старт», если же нет — рекомендую начать изучение с пункта «Как оно работает».

Руководство предназначено для продвинутых и уверенных в себе пользователей. Если вы не знаете, что такое оффсеты или категории, то вам стоит подумать дважды, хотите ли вы этим заниматься прямо сейчас.

Быстрый старт

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

Подготовка

1. Создайте черновики, которые в будущем станут вашими оффсетами. Наполните их вашим уникальным содержимым.

2. Создайте ещё один черновик (далее основной), который станет вашей опубликованной на Полигон страницей. Добавьте в него следующий код:

[[module ListPages category="draft" parent="." limit="1" order="name" offset="@URL|0"]]
%%content%%
[[/module]]

3. Вернитесь к ранее созданным черновикам-оффсетам, раскройте меню «Опции» внизу страницы, выберите опцию «Родитель» и для каждого черновика укажите только что созданный основной черновик.

4. Замените прямые ссылки в черновиках (типа draft:your-beautiful-article-0) на ссылки на оффсеты (типа draft:your-beautiful-article/offset/0). Держите в уме, что индексация для оффсетов начинается с 0, а не с 1.

5. Перейдите в основной черновик и проверьте работоспособность вашей статьи. Если всё работает корректно, приступайте к следующей главе.

Публикация

1. Создайте на Полигоне статью, которая будет являться вашей основной, и вставьте в неё немного видоизменённый код:

[[module ListPages category="fragment" parent="." limit="1" order="name" offset="@URL|0"]]
%%content%%
[[/module]]

2. Создайте в категории fragment статьи, которые станут вашими оффсетами. Можете скопировать содержимое из ваших черновиков-оффсетов.

3. Повторите пункты 3 и 4, описанные в главе «Подготовка». В ссылках замените draft на sandbox так, чтобы ссылки вели на только что созданные фрагменты-оффсеты.

4. Оформите основную статью, опубликованную на Полигоне, в соответствии с правилами публикации. Добавьте модуль рейтинга и, если необходимо, визуальную тему и прочие элементы, которые вы хотите видеть на каждом из оффсетов. Учтите, что всё, что добавлено в основную статью, отобразится на всех оффсетах.

Как оно работает

Итак, вы решили создать свою статью со стилистическим разделением на страницы. Помочь в этом вам может модуль ListPages, с которым вы могли встречаться ранее, например, в списках статей от определённых пользователей или по определённым тегам. Это мощный инструмент, документация по которому приведена в руководстве по вики-разметке. Если при чтении возникнут вопросы, то ответы вы сможете найти именно там.

Простыми словами, ListPages принимает в себя параметры и после этого поочерёдно перебирает статьи, которые им соответствуют, и выводит их содержимое на экран. Выводимая разметка зависит лишь от ключевых слов, используемых внутри тела модуля. В данном случае будет использовано только ключевое слово %%content%%, вставляющее всю вики-разметку найденной страницы.

Об основных терминах

Краткий перечень терминов для более простого понимания текста:

• Каноническое имя — имя статьи, отображаемое в поисковой строке браузера. Примеры: technotheology-0, scp-1470-ru. Данное имя используется внутри модулей как основное.

• Оффсет — это многозначный термин:

• • Оффсет (обыв.) — это дополнительная страница в статье, имеющая адрес /каноническое-имя/offset/номер-оффсета. Основное их преимущество — общий модуль рейтинга, что позволяет поставить одну оценку на все связанные страницы.

• • Оффсет (тех.) — это сдвиг списка найденных страниц. Подробнее об этом написано в главе «О параметрах ListPages».

• Категория — это технический термин для обозначения обособленного пространства имён статей. Категория всегда указывается в каноническом имени статьи перед знаком двоеточия. Например, для Полигона имя категории — sandbox, для черновиков — draft и так далее. Основное пространство имеет особое, невидимое имя категории _default.

• fragment — это имя категории, в которой исторически находятся все¹ оффсеты, а также дополнения для статей, которые должны использоваться только в них.

О параметрах ListPages

В пункте «Быстрый старт» уже был представлен пример кода, используемый в большинстве статей. Давайте его разберём.

• category="fragment" обозначает, что поиск будет происходить только по статьям в категории fragment. Вы можете указать любую категорию, даже произвольную, однако делать этого крайне не рекомендуется для сохранения единообразия контента на сайте.

• parent="." указывает на то, что искать нужно лишь те статьи, для которых текущая является родителем. Такими статьями должны быть созданные вами черновики.

• limit="1" обозначает количество отображаемых страниц в статье, в данном случае лишь одну. Менять это число не рекомендуется из-за возможного возникновения проблем с визуальной составляющей (конфликт визуальных тем, сломанные стили CSS, отсутствие смыслового разделения между оффсетами).

• order="name" указывает, что сортировка производится по каноническому имени статьи. Сортировка алфавитная, а потому fragment:offset-11 будет перед fragment:offset-2, будьте внимательны.

• • В качестве альтернативы можно использовать параметр order="created_at". В таком случае сортировка будет проводиться не по каноническому имени статьи, а по времени её создания. В таком случае вы должны проследить, чтобы оффсеты были созданы и заполнены в нужном вам порядке.

• offset="@URL|0" обозначает смещение списка найденных статей. @URL означает, что значение сдвига необходимо брать из адресной строки, а |0 — значение по умолчанию, принимаемое, если значение @URL не было найдено.

  

  В приложенном изображении представлены два варианта. Список найденных страниц представлен как цепочка последовательных клеток, на которые указывает указатель. В первом случае (верхняя половина) offset равен нулю (либо потому что мы находимся по адресу /sandbox:your-beautiful-article/offset/0 и модуль принимает значение из адреса, либо потому что мы находимся по адресу /sandbox:your-beautiful-article и модуль принимает значение по умолчанию, равное нулю), а потому на нашем экране отображается содержимое первой² клетки. Во втором случае (нижняя половина) offset равен двум, а потому список найденных статей смещается на две клетки влево и теперь указатель показывает на другую страницу, перенося уже её содержимое.

О содержимом оффсетов

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

Аналогичная логика применяется ко всему содержимому, не только визуальным темам.

О публикации на Полигоне

Полигон — это категория sandbox, и одна статья не может иметь две категории одновременно. Нельзя опубликовать фрагмент на Полигон — это захламляет его. Вместо этого вы должны создать свои оффсеты в категории fragment. Далее в вашей статье на Полигоне, используя невидимые комментарии, укажите ссылки на созданные вами оффсеты. Это не влияет на функционал, но очень поможет редакторам, АМС и, вполне возможно, переводчикам из других филиалов. Также данный список поможет вам, если ваша статья не будет удовлетворять стандартам качества и будет удалена — фрагменты автоматически не удаляются. Воспользовавшись этим списком, вы сможете легко очистить сайт от лишних оффсетов уже несуществующей статьи.

А нужно ли оно?

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

• обхода ограничения в 200 000 символов на статью,

• разделения большой истории на более мелкие сегменты для простоты чтения,

• изменения оформления на ходу, придания глубины истории (например если она затрагивает несколько СвОр со своими форматами),

• создания креативных и визуально поражающих историй,

• и т.п.

Использовать оффсеты необходимо ответственно и только если на то есть действительная необходимость. Нет нужды в их использовании для создания предупреждений перед прочтением или подобного — с этим справляется обычный CSS. Маленьким историям достаточно раскрывающихся спойлеров, использование дополнительных страниц — overkill.

Разумеется, здесь описаны не все возможности ListPages в создании дополнительных страниц для вашей статьи. Данная статья должна была дать вам понимание, как работает сам механизм, а как его применять — решать уже вам.

Теперь вы должны уметь самостоятельно создать свою статью с оффсетами. Удачи в написании!