Категории документации Discourse

[pacharanero (Marcus Baw)]

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

Я сам установил этот плагин, внимательно следуя инструкциям, но он работал не совсем так, как описывал @dennisjbr.

Может быть полезно привести пример необходимого Markdown-формата вместо ссылки на пример из Meta, потому что единственное ключевое правило — должен быть Markdown-список (маркированный или нумерованный). В документации сказано «список», но слово «список» в обычном английском языке может означать и немаркированные списки!

Это сработает как индексная тема:

* https://meta.discourse.org/t/discourse-doc-categories/322376
* Some Arbitrary Text: https://meta.discourse.org/t/discourse-doc-categories/322376

Это не сработает:

https://meta.discourse.org/t/discourse-doc-categories/322376
Some Arbitrary Text: https://meta.discourse.org/t/discourse-doc-categories/322376

Помимо этого, вы можете использовать заголовки Markdown для создания разделов и использовать несколько списков, но ничего не появится в боковой панели, если нет Markdown-списка. Я понимаю, что это может показаться очевидным и не должно было ввести в заблуждение других, но меня это поймало (глупо или нет), хотя я уже не новичок в Discourse, TC и плагинах.

[hugh (Hugh Lashbrooke)]

Я добавил более наглядный пример оформленной темы индекса в исходный пост здесь: https://meta.discourse.org/t/discourse-doc-categories/322376#p-1584993-formatting-index-topics-4

Посмотрите на это и дайте знать, если у вас всё ещё не получается.

[pacharanero (Marcus Baw)]

Мне всё нравится, @hugh!

[MarcP]

У меня есть AI-персона для моей категории документации. Возникали ли мысли о том, чтобы сделать AI-персону доступной для анонимных пользователей? Я думаю, хотя бы в виде временного анонимного чата в личных сообщениях. Это вообще возможно?

[MarcP]

Когда вы переходите на страницу, которая находится глубоко в индексе (требует прокрутки для доступа), главная страница также прокручивается вниз до позиции где-то посередине: например, на этом элементе документации

[hugh (Hugh Lashbrooke)]

Спасибо, что обратили на это внимание! Мы посмотрим, что можем сделать, чтобы в будущем этого не происходило.

[Heliosurge (Dan DeMontmorency)]

@Marcus Baw

Заголовки Markdown создают разделы и позволяют использовать несколько списков, но в боковой панели ничего не появится, если нет списка Markdown. Я понимаю, что это довольно очевидно и, возможно, не сбило с толку никого другого, но меня это подвело (наивно или нет), хотя я не новичок в Discourse, TC и плагинах.

На самом деле, при документировании чего-либо никогда не следует считать что-то «очевидным». Такая обратная связь жизненно важна для любого типа проекта, чтобы обеспечить ясность.

Любой написанный текст обычно кажется понятным автору из-за его глубокого понимания того, что он написал. Для других же, напротив, это может быть менее ясно.

Я сам не люблю термин «интуитивно понятный», так как что-то является интуитивно понятным только в том случае, если у человека есть опыт использования чего-то подобного.

[dennisjbr]

Спасибо! Это очень помогает.

[James_Harakaly]

Отличная работа, все!

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

Я пытаюсь использовать этот плагин для организации пользовательских проектов на уровне категорий.

Мы создаем форум, где будут размещаться различные проекты пользователей. Изначально все они находились в категории «Проекты», поэтому при нажатии на неё отображались все подкатегории с перечислением отдельных проектов в приятном интерфейсе (что-то вроде рынка проектов).
Однако при таком подходе мы теряем один уровень иерархии данных, поскольку отдельные проекты становятся подкатегориями вместо категорий.

Я был в восторге, когда нашел этот плагин, так как думал, что он идеально подойдет для организации всех проектов на уровне категорий, что позволит нам лучше структурировать данные внутри проектов.

Теперь я создаю отдельные проекты как отдельные категории (например, «рыболовная приманка», «проект 2», «проект 3») и использую плагин категорий документации, чтобы создать оглавление всех проектов. Это позволит пользователям нажимать на новую категорию «Проекты», управляемую плагином категорий документации, и использовать выпадающее меню для навигации по подкатегориям и темам, которые мы включим в индексную тему.

Есть ли способ отображать категории в средней колонке, чтобы это напоминало страницу «Все категории» в обычной ленте Discourse?

Я хочу, чтобы при нажатии на категорию «Проекты» в документации все проекты отображались в меню слева, а также показывались в виде блоков в основной ленте, как это обычно происходит с подкатегориями. Мне разрешили прикрепить только одно изображение к этому сообщению, поэтому я добавил изображение проектов в меню слева, но хотел бы видеть блоки категорий в центре, где сейчас отображается мой пост с темой.

Заранее спасибо за любую помощь и рекомендации.

[qianping_chen (rouin)]

Можете добавить «относительные ссылки», например «/t/topic/463», что было бы очень эффективно для смены «доменных имен» без больших затрат труда.

[MarcP]

@qianping_chen

что было бы очень эффективно для изменения «доменных имен» без особых усилий.

Сейчас это не требует больших усилий. Просто выполните поиск и замену — как часто вы меняете домены?

[hugh (Hugh Lashbrooke)]

@James Harakaly

Я хочу, чтобы при клике на категорию «Документация по проектам» в левом меню отображался список всех проектов, а также чтобы они показывались в виде блоков в основной ленте, как это обычно происходит с подкатегориями.

Это звучит как то, что мы реализовали здесь на Meta для подкатегорий документации.

Вы можете видеть подкатегории в основном представлении, и они также связаны в боковой панели здесь: Documentation - Discourse Meta

Чтобы это работало, мы создали индексную тему для родительской категории документации, включающую ссылки на каждую подкатегорию: Documentation Index.

Помогло ли это вам найти подходящее решение для вашего экземпляра?

[Heliosurge (Dan DeMontmorency)]

@MarcP

@qianping_chen

что было бы очень эффективно для изменения «доменных имен» без больших усилий.

В настоящее время это не требует больших усилий. Просто выполните поиск и замену — как часто вы меняете домены?

Поскольку относительные ссылки уже работают. Почему бы не добавить эту возможность и тем самым устранить ненужные усилия? В конце концов, это внутренние ссылки, и это способствовало бы достижению паритета в Discourse, так как внутренние ссылки также работают в различных темах и плагинах.

[James_Harakaly]

Спасибо, Хью!

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

В итоге я нашёл и установил плагин для под-под-категорий. Теперь я использую его, чтобы группировать подкатегории, которые фактически выполняют роль «категорий», поскольку ниже них есть два уровня распределения данных: под-под-категории и темы.

Это позволило мне достичь главной цели — увеличить количество уровней распределения данных и организации в рамках наших пользовательских проектов. Теперь я использую под-под-категории вместе с плагином, чтобы получить лучшее из обоих миров на уровне черновых категорий.

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

Вот основные категории проектов: BETA — будут и другие подкатегории.

А вот как работают «под-под-категории», превращая подкатегорию в категорию.
Вместе с удобной навигацией по индексной теме.

Ещё раз спасибо за всю работу, которую вы проделываете.
Надеюсь, в этом посте я выразился чуть понятнее.

Я нашёл решение, которым мы очень довольны: это комбинация двух плагинов.

[hugh (Hugh Lashbrooke)]

Я рад, что вы нашли решение, которое вам подходит!

[hellekin]

В чём преимущество этого плагина по сравнению с устаревшим плагином для документации?

В устаревшем плагине я мог размещать документацию в любой категории, при условии, что я поддерживаю теги. Теперь, кажется, все темы документации должны находиться в одной категории. Так ли это? В таком случае это немного теряет контекст, поскольку некоторые (существующие) документы могут относиться к конкретным группам/категориям (например, доступны только персоналу).

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

OT комментарий о «callouts»

@MarcP

Различные типы callouts

HedgeDoc использует следующее расширение Markdown для поддержки callouts (они называют это alert areas):

### Alert Area

:::success
Да :tada:
:::

:::info
Это сообщение :mega:
:::

:::warning
Осторожно :zap:
:::

:::danger
О нет! :fire:
:::

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

(это было бы довольно легко стилизовать с помощью CSS, если задать класс).

OT комментарий о лени и ИИ

@Jagster

Я ленив, поэтому не делал это вручную, а использовал ИИ форума.

Можете представить, сколько избыточной энергии и воды расходуется всего на три строки Markdown, которые вы могли бы просто скопировать и вставить вручную?

OT комментарий об относительных и абсолютных URL

@qianping_chen

Можете добавить «относительные ссылки», например «/t/topic/463», что было бы очень эффективно для изменения «доменных имен» без больших затрат труда.

На самом деле, копирование и вставка URL тем проще, а если вы меняете домен, вы, скорее всего, будете экспортировать/импортировать темы, и Discourse сам заменит домен.

---

После некоторых экспериментов вот мои (временные) выводы:

1. Использование темы описания категории для предоставления индекса документации полезно (например, Singular Docs - Documentation - petites singularités).
2. Категория документации верхнего уровня позволяет использовать подкатегории для изменения индекса боковой панели документации (например, «Установка Ruby» появляется под «Руководствами» на Documentation - petites singularités, но под «Советами и подсказками» на Sysadmin Docs - petites singularités), чтобы обеспечить хорошую структуру (см. Documentation здесь, где подкатегории отображаются в виде блоков).
3. Темы документации могут находиться где угодно на форуме, включая закрытые пространства, хотя индекс документации затем раскрывает их существование.
4. Боковая панель в настоящее время нестабильна:
   • иногда отображает URL, иногда заголовок;
   • иногда только префиксный текст;
   • при выходе из системы могут отсутствовать некоторые проиндексированные темы.
5. При миграции с устаревшего плагина для документации ссылку на документацию необходимо воссоздать в пользовательском разделе боковой панели (но её можно было бы сгенерировать автоматически, изменив /docs на категорию документации в настройках плагина, или создав/изменив постоянную ссылку /docs для ссылки на эту категорию).
6. Ссылка «Вернуться на форум» кажется странной, потому что темы документации остаются темами форума: мы всё ещё там читаем документацию!
7. Фильтрация пока не учитывает названия (под)категорий, к которым относится тема документации.

[MarcP]

Последнее обновление вносит небольшую ошибку в интерфейсе при наличии полосы прокрутки.

Также считаю, что поле поиска с фильтром было бы гораздо эффективнее, если бы по умолчанию оно просто выполняло пользовательский запрос поиска в текущей категории (вместо того чтобы задавать этот вопрос при отсутствии результатов). Заголовки очень короткие, поэтому в большинстве случаев пользователь, не знакомый с темой, не найдёт ничего по тому, что он введёт.

@hellekin

• Ссылка «Назад на форум» кажется странной, потому что темы документации остаются темами форума: мы всё ещё находимся там, читая документацию!

Однако вы теряете обычную боковую панель «форума», поэтому ссылка «Назад на форум» здесь имеет смысл.

[kakaroto (Youness Alaoui)]

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

Теперь я застрял, пытаясь понять, как добавить заголовок категории и блоки подкатегорий, как показано здесь:

Я не вижу никаких настроек для включения или отключения этого, и, к сожалению, они просто не появляются.
Если у кого-то есть идеи, буду благодарен за подсказку.
Спасибо.

[Moin]

Category Banners

Summary Category Banners uses existing category details to create banners for your category pages (for tags check out Discourse Tag Banners). Preview Preview on Discourse Theme Creator Repository Link https://github.com/discourse/discourse-category-banners New to Discourse Themes? Beginner’s guide to using Discourse Themes Install this theme component Features Category Banners uses existing category details to cr…

Display boxes for subcategories above topic list

This guide explains how to display boxes for subcategories above the topic list in Discourse. Required user level: Administrator (or moderator if the moderators manage categories setting is enabled) There are four ways to display a list of sub-categories within the parent category: in rows (the default style) in rows with a list of some featured topics in boxes with only the name, logo, and description in boxes with name, logo, and a list of some featured t…

[omarfilip]

Отсутствие фильтрации по тегам значительно снижает полезность плагина. В сообществе, где один документ может относиться к нескольким категориям, фильтрация по тегам является обязательной.

Например, документ с названием «Сборка шасси» может относиться к нескольким моделям самолетов и также содержать несколько тегов. Найти нужный документ с помощью фильтрации по тегам очень просто.

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

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