 |
Обзор | DiscoTOC позволяет в один клик создать оглавление для вашей темы. |
 |
Предпросмотр | Beginner's guide to using Discourse Themes (откройте ссылку в новой вкладке) |
 |
Ссылка на репозиторий | https://github.com/discourse/DiscoTOC |
 |
Не знакомы с темами Discourse? | Посетите официальную страницу с Руководством для начинающих по использованию тем Discourse |
Примеры
Рабочий стол
Мобильное устройство
Возможности
toc = table of contents (оглавление)
- В один клик создайте список оглавления (TOC) на основе текущего содержимого, используя кнопку настроек в меню.
- TOC всегда отображается на странице — прокрутка содержимого синхронизируется со ссылками на разделы темы.
- При прокрутке по теме соответствующий пункт оглавления подсвечивается (становится зеленым).
- Добавляет атрибуты к заголовкам (вы можете ссылаться на конкретные разделы из других тем/сообщений).
- При клике на ссылку в TOC браузер переходит к соответствующему месту в тексте (синхронная прокрутка).
- Добавляет копируемую ссылку для каждого заголовка (по желанию).
- Поддержка RTL (справа налево).
- Цветовая схема адаптируется под вашу текущую тему.
Как это работает
По умолчанию заголовки текущего содержимого помечаются как TOC (с помощью кнопки в редакторе). Если ваша тема уже помечена, она также преобразуется в TOC (в зависимости от иерархии заголовков). Все заголовки преобразуются в оглавление — это означает, что заголовки в вашем Markdown-файле должны быть правильно настроены. Если иерархия заголовков нарушена, результат преобразования будет некорректным.
# заголовок 1
## заголовок 2
### заголовок 3
#### заголовок 4
##### заголовок 5
###### заголовок 6
Вы можете изменять уровни заголовков, но должны сохранять правильную иерархию.
# заголовок 2
## заголовок 3
## заголовок 3
### заголовок 4
## заголовок 3
# заголовок 2
и так далее...
Чтобы ссылки работали корректно, все заголовки должны иметь атрибут id.
Компонент автоматически проверяет наличие id у заголовков. Если id присутствует, компонент работает эффективнее. Атрибут id также полезен при ручном создании тем.
Если у заголовка нет id, компонент автоматически создаст его на основе текста заголовка (необходимые символы будут автоматически удалены).
После выполнения всех вышеуказанных действий TOC создаст ссылки на соответствующие разделы текста, как показано на изображении ниже:
Настройки
У этого компонента только одна настройка — иконка TOC (изображение будет использоваться в последующих настройках; официально не рекомендуется изменять эту иконку).
Перевод и локализация
Этот компонент требует перевода очень небольшого количества текста — только следующие три поля:
table_of_contents: "оглавление"
Это отображается при открытии TOC на мобильном устройстве.
insert_table_of_contents: "Вставить оглавление"
Это отображается при вставке оглавления в страницу темы.
topic_will_contain_a_table_of_contents: "Эта тема будет содержать оглавление"
Это отображается на странице предпросмотра справа при редактировании содержимого темы.
Как создать заголовок
- Заголовки содержимого должны создаваться с правильной синтаксической структурой.
- Нажмите на опцию меню на странице (доступно только для обычных тем и сообщений; в ответах и личных сообщениях эта опция не отображается).
- Вставьте в страницу темы.
Что происходит с виджетом прогресса чтения при использовании TOC
Как вы, возможно, знаете, на странице нельзя одновременно отображать прогресс чтения и TOC.
Официальное решение: если при чтении первого сообщения существует TOC, на странице отображается только TOC, а виджет прогресса чтения игнорируется.
Когда вы переходите за пределы первого сообщения, TOC перестает отображаться, и вместо него показывается полоса прогресса чтения всего содержимого.
Проще говоря, TOC работает только для первого сообщения; для последующих сообщений используется полоса прогресса чтения.
Отображение на мобильных устройствах и рабочих столах одинаковое.
Проблемы при использовании этого компонента
По словам автора и официальной информации, на данный момент проблем при использовании этого компонента не выявлено.
Вся обработка содержимого выполняется на стороне клиента (на языке разработчиков — всё происходит на фронтенде), поэтому предоставление данных на бэкенде не затрагивается.
После отключения компонента всё содержимое возвращается к исходному виду.
Ограничения использования
Этот компонент использует стандартную разметку тем.
Если используемая вами разметка модифицирует заголовки, компонент TOC не сможет работать корректно.
Например, известно, что при использовании темы Vincent компонент не работает.
Поддержка некоторых популярных тем — следующая задача, которую необходимо решить для этого официального плагина.
Разработчики
Официальный автор разработал компонент на основе библиотеки Greg Franko’s tocify.js.
Однако, к сожалению, эта библиотека давно не обновлялась, поэтому автор удалил из неё много ненужного кода и функций, а затем интегрировал необходимые функции в Discourse.
Размер компонента составляет около 4 КБ (при сжатии gzip).
Автор также благодарит @erlend_sh за отличные предложения и @david за помощь в переводе.
Планы на будущее (TODO)
- Отображение TOC в реальном времени во время редактирования (это может потребовать значительных ресурсов).
- Поддержка популярных тем для отображения TOC.
- Автоматическое копирование ссылки на заголовок в буфер обмена при клике на кнопку ссылки.
По поводу этого релиза автор отмечает: это ранняя версия. Если у вас есть вопросы, предложения или идеи по улучшению, пожалуйста, свяжитесь напрямую с оригинальным автором.
Официальная информация, ссылки и обсуждения по этому компоненту доступны на странице: DiscoTOC - automatic table of contents.
Техническая помощь (на русском языке)
Если у вас возникнут дополнительные вопросы или потребуется помощь, посетите наш веб-сайт (на русском языке): iSharkFly - 飞鲨