Документация Discourse

[Discourse]

Этот плагин выводится из эксплуатации в пользу экспериментального плагина Doc Categories. Мы будем продолжать поддерживать Docs, пока новый плагин не перестанет считаться экспериментальным.

	Краткое описание	Discourse Docs позволяет находить и фильтровать темы базы знаний
	Ссылка на репозиторий	https://github.com/discourse/discourse-docs
	Руководство по установке	Как установить плагины в Discourse

Поскольку это #официальный плагин, поддерживаемый командой Discourse, запросы на Support, Contribute > Bug, Contribute > UX и Contribute > Feature можно создавать в соответствующих категориях здесь, на Meta, указывая соответствующий тег плагина. Нажмите на ссылку ниже, чтобы начать.

Поддержка Баг UX Функция

Возможности

Плагин Discourse Docs — это мощный инструмент, который превращает ваш форум Discourse в базу знаний, создаваемую сообществом. Он предоставляет отдельный раздел Docs, где пользователи могут создавать, обновлять и курировать документацию. Этот плагин включает кнопку Docs, которая обеспечивает легкий доступ к этому разделу. Это отличный способ использовать коллективные знания вашего сообщества и предоставить централизованный ресурс для важной информации.

По сути, Docs упрощает поиск тем в стиле базы знаний в пределах определенного набора категорий и/или тегов.

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

Нужно найти тему базы знаний из другого места в Discourse? Используйте новый помощник поиска: in:kb.

Настройка

1. Включите плагин, активировав параметр docs enabled.

2. Добавьте категории и теги в параметры docs categories и docs tags.

3. Найдите ссылку Docs в навигационном меню.

4. Получайте выгоду от более легкого доступа к знаниям!

Параметры

Имя	Описание
docs enabled	Включить плагин Docs
docs categories	Список слаг-адресов категорий для включения в docs
show tags by group	Организуйте теги с помощью групп тегов. Создавайте группы для категоризации связанных тегов.
docs tag groups	Группы тегов, используемые для отображения тегов по группам
docs tags	Список тегов для включения в docs
docs add solved filter	Добавляет фильтр для решенных тем — требуется установка и включение Discourse Solved
docs add to top menu	Добавляет ссылку в верхнее меню для перехода к просмотру Docs
docs add search menu tip	Добавляет подсказку “in:docs” в случайные подсказки меню поиска

Полезные дополнения

Фильтр карточек Discourse Docs

Summary Discourse Docs Card Filter используется вместе с Discourse Docs Plugin и позволяет размещать «карточки», которые действуют как кликабельный фильтр для более быстрого получения результатов фильтрации при входе пользователей на страницу /docs. Предпросмотр Предпросмотр на Discourse Theme Creator Ссылка на репозиторий https://github.com/discourse/discourse-docs-card-filter Новичок в темах Discourse? Руководство для н…

Переименование пути /docs

Если у вас есть доступ к серверу, вы можете изменить путь ссылки /docs, добавив переменную окружения DISCOURSE_DOCS_PATH: в ваш файл app.yml:

Чтобы изменения вступили в силу, вы можете либо выполнить ./launcher rebuild app, либо, поскольку это переменная окружения, выполнить ./launcher destroy app && ./launcher start app, чтобы минимизировать время простоя. Дополнительная информация доступна здесь — Set Environmental Variables

Возможно, вам также захочется изменить отображаемый текст сайта, чтобы он соответствовал. Вы можете найти все вхождения слова “docs” на странице /admin/customize/site_texts, но основные из них:

• js.docs.title
• js.sidebar.docs_link_text

Размещается у нас? Переименование пути /docs доступно только в нашем корпоративном плане. Пожалуйста, свяжитесь с нами, если вы хотите узнать больше.

История разработки

Плагин Docs был продолжением темового компонента Knowledge Explorer.

[Hyan]

Привет, сообщество Discourse,

При выполнении спецификации я получил ошибку ниже. Я не менял никаких файлов. Можно ли игнорировать эту ошибку?

➜  discourse git:(main) ✗ LOAD_PLUGINS=1 bundle exec rspec plugins/discourse-docs/spec

Randomized with seed 57815
...................................F

Failures:

  1) Discourse Docs | Index topic excerpts when the theme modifier serialize_topic_excerpts is true shows the excerpts
     Failure/Error: expect(page).to have_css(".topic-excerpt", text: topic_1.excerpt)
       expected to find css ".topic-excerpt" but there were no matches

     [Screenshot Image]: /xxxx/discourse/discourse/tmp/capybara/failures_r_spec_example_groups_discourse_docs_index_topic_excerpts_when_the_theme_modifier_serialize_topic_excerpts_is_true_shows_the_excerpts_460.png

     ~~~~~~~ JS LOGS ~~~~~~~
     ~~~~~ END JS LOGS ~~~~~

     # ./plugins/discourse-docs/spec/system/docs_index_spec.rb:52:in `block (4 levels) in <main>'
     # ./spec/rails_helper.rb:469:in `block (2 levels) in <top (required)>'

Finished in 13.16 seconds (files took 2.79 seconds to load)
36 examples, 1 failure

Failed examples:

rspec ./plugins/discourse-docs/spec/system/docs_index_spec.rb:50 # Discourse Docs | Index topic excerpts when the theme modifier serialize_topic_excerpts is true shows the excerpts

Randomized with seed 57815

[JammyDodger]

Вам удалось решить это, @Hyan?

[tpetrov (Toni Petrov)]

Привет, Сэм, не кажется ли тебе логичным с точки зрения SEO, чтобы rel=canonical тем указывал на оригинальную тему? Например, Dark/Light Mode Toggle - theme-component - Docs - Discourse Meta → Dark/Light Mode Toggle - theme-component - Discourse Meta? Мне интересно, не конкурируют ли две версии страницы друг с другом в алгоритмах Google.

[sam (Sam Saffron)]

Да, безусловно, нам стоит что-то сделать в этом направлении

[Hyan]

Извини, @JammyDodger, у меня в последнее время не было возможности запустить Spec. Сейчас я занимаюсь не работой, связанной с Discourse Docs, а другими задачами. Но я дам тебе знать, как только появится возможность.

[martyn_thomas]

Можно ли изменить иконку рядом с разделом «Документация» в гамбургер-меню, заменив значок ссылки/цепочки на другой?

[martyn_thomas]

Этот плагин отлично подходит для того, чтобы разместить все категории документов в одном месте, избавив от необходимости дублировать их в списке категорий (спасибо плагину Discourse Category Hider). Однако мы обнаружили проблему:

В плагине Docs / на экране Docs невозможно редактировать существующие документы или создавать новые. Это означает, что вам приходится переходить в исходную категорию, чтобы найти тему/документ для редактирования… то есть документ должен быть доступен более чем в одном месте.

Существует ли возможность включить редактирование тем/документов (если пользователь принадлежит к правильной группе пользователей) непосредственно внутри плагина Docs?

[Moin]

@Мартин Томас

Вы должны перейти в исходную категорию, чтобы найти тему или документ для редактирования.

Помогает ли ссылка «Посмотреть обсуждение по этой теме» внизу для перехода к теме и её редактирования?

[digitaldominica]

Привет, у меня есть довольно раздражающая проблема, и я не понимаю, почему она возникает.

Когда я создаю документ, он попадает в раздел документов и работает как положено. Однако, если документ каким-либо образом редактируется, макет списка тем документов переключается обратно на стандартный макет темы Discourse при клике, и не отображается фактический макет документа.

Я заметил, что через несколько минут он снова возвращается к макету темы документа и выглядит так, как должно быть. Не могли бы вы подсказать, что может быть причиной этого?

Примечание: я также использую компонент темы «Миниатюры тем» и установил режим миниатюр документов в «список».

[digitaldominica]

Нашёл проблему: похоже, что при использовании темы «topic-list-excerpts» (Topic List Excerpts) или компонента темы «Topic lists Thumbnails» (Topic List Thumbnails) ссылка href ведёт на страницу темы Discourse, а не на документацию KB?topic=xxx, из-за чего происходит перенаправление на темы Discourse.

Есть ли способ сохранить путь URL в документации на @sam, или стоит обратиться к @david?

[civitas_john (John Chen)]

Привет,

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

Мне интересно, не лучше ли автоматически сворачивать боковую панель, если ширина окна недостаточна; однако даже после сворачивания боковой панели содержимое всё равно выходит за пределы.

[Nebthtet]

Спасибо за замечательное дополнение. Но у меня один вопрос: есть ли возможность убрать ссылку из контекстного меню с «гамбургером»? Я добавил её вручную в секцию «всегда видна» (так как хотим использовать эту функцию для демонстрации длинного пользовательского контента, например, статей и т.д.), и теперь она отображается дважды:

Обе опции с более светлым фоном ведут на /docs

[Arkshine]

Думаю, вы можете скрыть это с помощью CSS здесь:

.sidebar-section-link-wrapper[data-list-item-name="docs"] {
    display: none;
}

[Nebthtet]

Работает отлично! Большое спасибо!

[rly]

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

[wsxiaolin]

@civitas_john

Даже после сворачивания боковой панели контент всё ещё выходит за границы.

Я снова проверил ту же ссылку на устройстве с той же шириной области просмотра. Хотя до сворачивания боковой панели переполнение всё ещё присутствовало, я обнаружил, что после его сворачивания переполнения нет, и отображение выглядит нормально и эстетично.

[supermathie (Michael Brown)]

Я удивлён, что в Документах порядок поиска по умолчанию — не «По релевантности», а «Дата активности».

Возможно ли искать по релевантности?

[thaidb]

Сегодня я опубликовал несколько тем в категории «Документация», но они не отображаются на странице «Документация». Я отключил плагин документации и снова включил тему, но темы всё ещё не отображаются.
Спасибо!