 |
Краткое описание | DiscoTOC позволит вам в один клик генерировать интерактивное оглавление для ваших тем! |
 |
Предпросмотр | Предпросмотр в Discourse Theme Creator |
 |
Ссылка на репозиторий | https://github.com/discourse/DiscoTOC |
 |
Новичок в темах Discourse? | Руководство для начинающих по использованию тем Discourse |
Установить этот компонент темы
Примеры
Десктоп
Мобильная версия
Возможности
toc = оглавление
-
Автоматически генерирует всё оглавление через кнопку в меню настроек редактора
-
Оглавление всегда будет на экране — прокручивается вместе с содержимым, как виджет прогресса темы
-
По мере прокрутки разделов темы активный элемент в оглавлении будет подсвечиваться (синим цветом)
-
Каждая запись в оглавлении ссылается на якорь заголовка, поэтому вы также можете ссылаться на конкретный раздел из другой темы или сообщения
-
Клик по любой ссылке в оглавлении заставляет браузер перейти к соответствующему разделу (плавная прокрутка)
-
В темах с ответами кнопка Содержание / Хронология позволяет читателям переключаться между оглавлением и обычной хронологией темы. Выбор запоминается в браузере
-
Работает с плагином Discourse Docs
-
Опциональная поддержка оглавлений в ответах, а не только в первом сообщении
-
Поддержка RTL (справа налево)
Как это работает?
В двух словах: оно ищет заголовки в темах, помеченных для наличия оглавления (через кнопку в редакторе), и если текущая тема помечена, оно берет все заголовки и помещает их в оглавление (вложенные в порядке уровней заголовков) — это означает, что ваш Markdown должен быть синтаксически корректным.
# заголовок 1
## заголовок 2
### заголовок 3
#### заголовок 4
##### заголовок 5
Вы можете свободно переходить между уровнями заголовков, но порядок должен быть правильным
# заголовок 2
## заголовок 3
## заголовок 3
### заголовок 4
## заголовок 3
# заголовок 2
и т.д...
Несколько моментов о совместимости заголовков
- Включены
h1поh5.h6не включен - Заголовки внутри цитат игнорируются, поэтому цитаты не будут засорять оглавление
- Оглавление появляется только если в сообщении есть не меньше заголовков, чем указано в настройке минимальное количество заголовков для оглавления (по умолчанию 3)
Как работают ссылки в оглавлении?
Каждый заголовок в обработанном сообщении получает якорь в формате p-<id сообщения>-<slug заголовка>-<номер> — это цель ссылки заголовка. DiscoTOC ссылается на эти якоря, а не создает свои собственные.
Поскольку эти якоря включают позицию заголовка в сообщении, они меняются, если вы меняете порядок или названия заголовков. Если вы ссылаетесь на разделы из других мест, вы можете добавить стабильные именованные якоря над заголовком:
<div><a name="my-section"></a></div>
## Мой раздел
Затем ссылаться на /t/ваш-тег-темы/1234#my-section. Discourse позволяет использовать <a name="..."> в сообщениях. Собственные записи DiscoTOC будут по-прежнему использовать основные якоря заголовков, но ваши будут продолжать работать независимо от правок.
Настройки
| Имя | Описание |
|---|---|
| минимальный уровень доверия для создания оглавления | Необходимый уровень для отображения кнопки оглавления в редакторе |
| текст оглавления в редакторе | Текст, который появляется в начале редактора, указывая, что тема будет иметь оглавление |
| категории с авто-оглавлением | Автоматически включать категории |
| теги с авто-оглавлением | Автоматически включать оглавление в темах с этими тегами |
| включить оглавление для ответов | Позволяет создавать оглавления для ответов. Оглавления для ответов не зависят от настроек теги с авто-оглавлением и категории с авто-оглавлением и должны быть вставлены вручную |
| минимальное количество заголовков для оглавления | Минимальное количество заголовков в теме для отображения оглавления |
текст оглавления в редакторе — это то, что отображается в предпросмотре редактора, чтобы указать, что будет сгенерировано оглавление:
Переводы
| Перевод | По умолчанию |
|---|---|
| table_of_contents | оглавление |
| insert_table_of_contents | Вставить оглавление |
| jump_bottom | Перейти в конец |
| toggle_toc.show_timeline | Хронология |
| toggle_toc.show_toc | Содержание |
table_of_contents: "оглавление"
это используется для кнопки, открывающей оглавление на мобильных устройствах
insert_table_of_contents: "Вставить оглавление"
это используется как текст для кнопки оглавления в меню настроек редактора
toggle_toc.show_toc: "Содержание"
toggle_toc.show_timeline: "Хронология"
эти метки обозначают кнопку, переключаящую между оглавлением и хронологией темы
Как создать оглавление?
- Напишите тему с синтаксически корректными заголовками
- Нажмите кнопку оглавления в меню настроек редактора. По умолчанию она появляется только в первом сообщении темы; включите настройку включить оглавление для ответов, чтобы использовать её в ответах
- Готово.
Что происходит с виджетом прогресса темы, когда в теме есть оглавление?
Нет места, чтобы показывать их одновременно, поэтому в теме с оглавлением виджет прогресса темы скрыт, пока вы находитесь на первом сообщении, и вместо него вы видите оглавление. Как только вы прокрутите мимо первого сообщения, оглавление заменяется обычным виджетом прогресса темы, пока вы читаете ответы. (Если включено включить оглавление для ответов, ответ со своим оглавлением показывает его вместо этого.)
В темах с более чем одним сообщением кнопка Содержание / Хронология позволяет читателям переключаться между ними, и предпочтение запоминается в их браузере.
На узких экранах оглавление открывается как оверлей через кнопку в области прогресса темы.
Есть ли недостатки использования этого компонента?
Почти всё происходит на стороне клиента, поэтому вы можете удалить компонент в любой момент, и ваши сообщения будут отображаться так же, как и раньше. Единственное, что затрагивает ваше содержимое, — это кнопка в редакторе: она оборачивает сообщение в маркер <div data-theme-toc="true">, что сообщает компоненту, что у сообщения должно быть оглавление. Если вы удалите компонент, эта обертка останется в сообщении, но не будет иметь видимого эффекта.
Ограничения
Заголовки h6 и заголовки внутри цитат не включаются в оглавление.
Благодарности
Это началось как жесткая вилка библиотеки tocify.js Грэга Франко, и с тех пор было переписано как нативные компоненты Ember. Нет внешних зависимостей или запросов.
Большое спасибо @erlend_sh за множество ценных отзывов и @david за помощь с переводами.
спасибо!
