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

[Discourse]

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

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

Поскольку это #официальный плагин, поддерживаемый командой Discourse, запросы на #поддержку, сообщения об #ошибках, предложения по ux и #новым функциям можно направлять в соответствующие категории на 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 Card Filter

Summary Discourse Docs Card Filter is to be used with the Discourse Docs Plugin and allows you to place “Cards” that act as a clickable filter for quicker filter results upon entering the /docs page by your users. Preview Preview on Discourse Theme Creator Repository Link https://github.com/discourse/discourse-docs-card-filter New to Discourse Themes? Beginner’s guide to using Discourse Themes Install this theme comp…

Переименование пути /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 доступно только в нашем плане Enterprise. Свяжитесь с нами, если хотите узнать больше.

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

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

Размещено у нас? Этот плагин доступен во всех наших тарифных планах хостинга. https://www.discourse.org/plugins/docs.html

[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]

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