 |
Краткое описание | DiscoTOC позволит вам одним кликом сгенерировать интерактивное оглавление для ваших тем! |
 |
Предварительный просмотр | Предварительный просмотр на Discourse Theme Creator |
 |
Ссылка на репозиторий | https://github.com/discourse/DiscoTOC |
 |
Новичок в темах Discourse? | Руководство для начинающих по использованию тем Discourse |
Установить этот компонент темы
Примеры
Настольная версия
Мобильная версия
Возможности
toc = оглавление
-
Автоматически генерирует всё оглавление с помощью кнопки в меню настроек редактора
-
Оглавление всегда остаётся на экране — оно прокручивается вместе с контентом, как виджет прогресса чтения темы
-
При прокрутке разделов темы активный элемент в оглавлении выделяется (синим цветом)
-
Добавляет атрибуты id к заголовкам (вы можете ссылаться на конкретный раздел из другой темы или сообщения)
-
Нажатие на любую ссылку в оглавлении перемещает браузер к соответствующему разделу (плавная прокрутка)
-
Добавляет копируемую ссылку рядом с каждым заголовком (если вам нужно на него сослаться)
-
Поддержка правостороннего текста (RTL)
-
Цвета основаны на вашей текущей активной цветовой палитре
Как это работает?
Если коротко: компонент ищет заголовки в темах, которые помечены для создания оглавления (через кнопку в редакторе). Если тема помечена, он берёт все заголовки и помещает их в оглавление (вложенными в порядке уровней заголовков) — это означает, что ваш Markdown-код должен быть синтаксически корректным.
# заголовок 1
## заголовок 2
### заголовок 3
#### заголовок 4
##### заголовок 5
###### заголовок 6
Вы можете свободно переходить между уровнями заголовков, но порядок должен быть соблюдён:
# заголовок 2
## заголовок 3
## заголовок 3
### заголовок 4
## заголовок 3
# заголовок 2
и т.д.
Чтобы ссылки в оглавлении работали, у заголовков должны быть атрибуты id. Компонент проверяет, есть ли у заголовков уже такие идентификаторы, и если есть, то использует их. Это удобно, если вы когда-либо создавали оглавление вручную.
Если у заголовков нет идентификаторов, компонент сгенерирует их на основе текста заголовка (нежелательные символы удаляются).
После этого рядом с каждым заголовком добавляется ссылка, ведущая непосредственно к этому разделу:
Настройки
| Название | Описание |
|---|---|
| минимальный уровень доверия для создания оглавления | Минимальный уровень доверия, который должен быть у пользователя, чтобы видеть кнопку создания оглавления в редакторе |
| текст кнопки оглавления в редакторе | Текст, отображаемый в верхней части панели предварительного просмотра редактора, указывающий, что в теме будет оглавление |
| категории с автоматическим включением оглавления | Автоматически включать оглавление для тем в этих категориях |
| теги с автоматическим включением оглавления | Автоматически включать оглавление для тем с этими тегами |
| минимальный уровень заголовка для отображения оглавления | Минимальное количество заголовков в теме, необходимое для отображения оглавления |
Переводы
| Перевод | Значение по умолчанию |
|---|---|
| table_of_contents | table of contents |
| insert_table_of_contents | Insert table of contents |
| jump_bottom | Jump to end |
| toggle_toc.show_timeline | Timeline |
| toggle_toc.show_toc | Contents |
Тема содержит три строки, которые можно перевести или изменить.
table_of_contents: "table of contents"
Эта строка используется для кнопки, открывающей оглавление на мобильных устройствах.
insert_table_of_contents: "Insert table of contents"
Эта строка используется как текст для кнопки создания оглавления в меню настроек редактора.
topic_will_contain_a_table_of_contents: "This topic will contain a table of contents"
Это текст, который отображается в предварительном просмотре редактора, указывая, что для темы будет сгенерировано оглавление.
Как создать оглавление?
- Напишите тему с синтаксически корректными заголовками.
- Нажмите кнопку оглавления в меню настроек (появляется только при создании обычной темы — ответы и личные сообщения игнорируются).
- Готово.
Что происходит с виджетом прогресса чтения, если в теме есть оглавление?
Как вы, вероятно, догадываетесь, места для одновременного отображения обоих элементов недостаточно, поэтому компонент работает следующим образом:
В теме с оглавлением виджет прогресса чтения скрывается, пока первое сообщение находится на экране, и вместо него отображается оглавление.
Как только вы прокрутите первое сообщение, оглавление перестанет прокручиваться вместе с вами, и вместо него будет отображаться виджет прогресса чтения при просмотре остальных сообщений.
Таким образом, первое сообщение получает оглавление, а последующие сообщения — обычный виджет прогресса чтения.
Это происходит как на настольной, так и на мобильной версии.
Есть ли недостатки у использования этого компонента?
Никаких, насколько мне известно, все изменения происходят на стороне клиента. Вы можете легко удалить компонент, и ваши сообщения вернутся к тому виду, который был до его установки.
Ограничения
Этот компонент предполагает стандартную структуру темы. Поэтому он не будет работать с темами, изменяющими эту структуру, такими как тема Vincent. Поддержка популярных тем, изменяющих структуру, будет добавлена позже в виде настроек компонента.
Благодарности
Я начал с библиотеки tocify.js Грега Франко. Однако, похоже, она давно не обновлялась, поэтому это, по сути, форк, из которого удалены многие ненужные функции, а остальные интегрированы и стилизованы для Discourse.
Таким образом, внешних запросов нет, а общий размер составляет ~ 4 КБ в сжатом виде.
Большое спасибо @erlend_sh за множество ценных отзывов и @david за помощь с переводами.
Размещено у нас? Компоненты тем доступны для использования на наших тарифных планах Pro, Business и Enterprise.