Discourse 문서 카테고리

커스터마이징 플러그인
,
46

혼란과 어려움의 원인은 Index Topic이 특정 형식을 따라야 한다는 점인데, 이는 문서에서 (완전히 명확하게) 명시되어 있지 않기 때문일 수 있습니다. (최상위 게시물)

저는 이 플러그인을 직접 설치하여 설명을 꼼꼼히 따랐지만, @dennisjbr 님이 겪은 것과 정확히 동일한 방식으로 작동하지 않았습니다.

Meta 예시를 링크하는 것보다 필요한 Markdown의 예를 보여주는 것이 도움이 될 수 있습니다. 왜냐하면 핵심 규칙은 Markdown의 번호/불릿 리스트가 반드시 있어야 한다는 것이기 때문입니다. 문서에는 '리스트’라고만 되어 있지만, '리스트’라는 단어는 일반 영어 용법상 Markdown이 아닌 리스트를 포함할 수 있습니다!

다음은 Index Topic으로 작동합니다:

* 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, 플러그인에 대해 초보자가 아닙니다.

5개의 좋아요
49

원래 게시물에 포맷팅된 인덱스 토픽의 더 명확한 예를 추가했습니다: https://meta.discourse.org/t/discourse-doc-categories/322376#p-1584993-formatting-index-topics-4

확인해 보시고, 여전히 문제가 해결되지 않으면 알려 주세요.

8개의 좋아요
50

나한테는 괜찮아 보여 @hugh !

3개의 좋아요
51

문서 카테고리에 AI 페르소나를 하나 가지고 있습니다. 익명 사용자(anonymous)들을 위해 AI 페르소나를 사용할 수 있게 하는 것에 대해 논의가 있었나요? 적어도 임시 익명 채팅 DM 형태로라면 가능할 것 같습니다. 이게 아예 불가능한 건가요?

52

인덱스에서 매우 아래쪽에 있는 페이지를 방문하면(도달하려면 스크롤이 필요함), 메인 페이지도 중간 어딘가로 스크롤됩니다. 예를 들어 이 문서 항목에서 확인할 수 있습니다.

2개의 좋아요
53

이 부분을 지적해 주셔서 감사합니다! 앞으로 이를 방지하기 위해 어떤 조치를 취할 수 있는지 검토해 보겠습니다.

3개의 좋아요
55

사실 문서화를 할 때 어떤 것이 "자명하다"고 생각해서는 안 됩니다. 이러한 피드백은 명확성을 보장하기 위해 어떤 유형의 프로젝트에서든 필수적입니다.

작성된 내용은 작성자가 작성한 내용에 대한 깊은 이해를 가지고 있기 때문에 일반적으로 작성자에게는 명확하게 느껴집니다. 반면, 다른 사람들에게는 덜 명확하게 느껴질 수 있습니다.

저는 "직관적인(intuitive)"이라는 용어를 싫어합니다. 유사한 것에 대한 경험이 있을 때만 직관적일 수 있기 때문입니다.

7개의 좋아요
56

감사합니다! 정말 많은 도움이 됩니다.

57

모두들 이 플러그인에 대한 놀라운 작업을 해주셨네요!!

초보자인데 미리 양해 부탁드립니다! 꽤 오랫동안 혼자서 해결책을 찾아보고 있지만 어디에서도 답을 찾을 수 없네요. :frowning:

저는 이 플러그인을 카테고리 수준에서 개별 사용자 프로젝트를 정리하는 용도로 사용하려고 합니다.

우리는 다양한 사용자 프로젝트가 포함된 포럼을 만들고 있습니다. 원래는 모든 프로젝트를 “projects” 카테고리 아래에 두었기 때문에, 누군가가 projects를 클릭하면 모든 개별 프로젝트가 나열된 하위 카테고리 박스들을 깔끔한 UI로 확인할 수 있었습니다(일종의 프로젝트 마켓플레이스처럼).
하지만 그렇게 하면 개별 프로젝트가 카테고리 대신 하위 카테고리로 시작하게 되어 데이터 조직의 한 수준을 잃게 됩니다.

이 플러그인을 발견했을 때 정말 흥분했습니다. 모든 프로젝트를 카테고리 수준에서 정리할 수 있어 프로젝트 내부에서 더 나은 데이터 조직을 만들 수 있으리라 생각했기 때문입니다.

그래서 이제 개별 프로젝트를 개별 카테고리(예: 낚시 루어, 프로젝트 2, 프로젝트 3)로 만들고, doc categories 플러그인을 사용하여 모든 프로젝트의 목차(ToC)를 기본적으로 생성하고 있습니다. 이렇게 하면 사람들이 doc cat 플러그인으로 실행되는 새로운 projects 카테고리를 클릭하고, 드롭다운 메뉴를 통해 우리가 인덱스 토픽에 나열하기로 선택한 하위 카테고리와 토픽을 탐색할 수 있습니다.

카테고리가 중앙 열에 표시되어, 일반 Discourse 피드의 “모든 카테고리” 페이지와 유사한 뷰를 만들 수 있는 방법이 있을까요?

projects doc 카테고리를 클릭했을 때 왼쪽 메뉴에 모든 프로젝트가 나열되도록 하되, 메인 피드에서도 하위 카테고리처럼 박스 형태로 표시되기를 원합니다. 이 게시물에는 이미지만 한 장 첨부할 수 있어서 왼쪽 메뉴의 프로젝트 이미지를 첨부했는데, 제 토픽 게시글이 표시되는 중앙 부분에 카테고리 박스가 표시되기를 원합니다.

도움과 조언을 미리 감사드립니다.

image
image1267×619 125 KB

3개의 좋아요
58

“상대 경로”(예: “/t/topic/463”)를 추가할 수 있을까요? 도메인 이름을 변경할 때 많은 작업을 하지 않고도 효과적으로 처리할 수 있어 매우 유용할 것 같습니다.

1개의 좋아요
59

현재는 많은 작업이 아닙니다. 검색 및 치환만 수행하면 됩니다. 도메인을 얼마나 자주 변경하시나요?

2개의 좋아요
60

이것은 저희가 Meta에서 문서 하위 카테고리를 위해 했던 작업과 비슷해 보입니다.

메인 뷰에서 하위 카테고리를 확인할 수 있고, 여기 사이드바에도 링크되어 있습니다: Documentation - Discourse Meta

이 기능을 구현하기 위해, 각 하위 카테고리로의 링크를 포함하는 상위 문서 카테고리의 인덱스 토픽을 추가했습니다: Documentation Index

이 정보가 여러분의 인스턴스에서 좋은 해결책을 찾는 데 도움이 되나요?

3개의 좋아요
61

상대 링크가 이미 작동하고 있습니다. 그렇다면 왜 추가해서 불필요한 작업을 없애지 않나요? 결국 이거는 내부 링크이고, 이렇게 하면 Discourse의 동등성을 높이는 데 기여하게 됩니다. 내부 링크는 다양한 TC 및 플러그인에서도 작동하니까요.

1개의 좋아요
62

휴, 감사합니다!
여러분이 서브카테고리(subcats)를 위해 하고 있는 일은 올바른 방향을 향해 가고 있는 것 같습니다. 하지만 저는 주로 UI에서 중간 열의 상자에 서브카테고리와 마찬가지로 카테고리(Categories)가 표시되도록 하고 싶었습니다.

결국 서브-서브카테고리(sub-sub-cat) 플러그인을 찾아서 설치했습니다. 이제 이 플러그인을 사용해 서브카테고리를 그룹화하고 있습니다. 서브카테고리 아래에 서브-서브카테고리와 토픽이라는 두 단계의 데이터 분배가 있기 때문에, 서브카테고리가 실제로 ‘카테고리’ 역할을 하게 되었습니다.
이것은 사용자 프로젝트 내에서 데이터 분배와 조직화 수준을 높이라는 제 주요 목표를 충족시켰습니다. 이제 저는 서브-서브카테고리와 플러그인을 함께 사용해 스텁 카테고리(stub category) 수준에서 두 가지의 장점을 모두 얻고 있습니다.
처음에는 덕 카테고리(duck categories) 플러그인만으로 프로젝트 카테고리를 만들려고 했으나, 왼쪽에 메뉴만 있고 사용자가 탐색할 중간 영역이 비어 있는 UI가 마음에 들지 않았습니다. 그래서 (카테고리인) 프로젝트들이 서브카테고리가 보통 하듯이 ‘카테고리(모든 프로젝트)’ 내에서 표시되도록 하고 싶었습니다. (마지막 게시물에 있는 목업 사진 참고)

image
image1166×432 66.6 KB

여기 프로젝트의 메인 카테고리입니다: BETA - 다른 서브카테고리가 추가될 예정입니다

image
image1316×477 54.4 KB

그리고 여기는 '서브-서브카테고리’가 서브카테고리를 카테고리로 변환하는 역할을 수행하는 모습입니다.
인덱스 토픽의 쉬운 내비게이션과 함께.

image
image1309×652 132 KB

image
image1119×671 67.5 KB

여러분이 하시는 모든 작업에 대해 다시 한번 감사드립니다.
이 게시물에서 조금 더 명확하게 설명한 것 같아 좋네요. :frowning:

우리가 매우 만족하는 해결책을 찾았으며, 이는 두 플러그인의 조합입니다.

2개의 좋아요
63

본인에게 적합한 해결책을 찾으셨다니 기쁩니다!

2개의 좋아요
64

이 플러그인은 기존(레거시) 문서 플러그인보다 어떤 장점이 있나요?

기존 플러그인에서는 태그를 관리하기만 하면 어떤 카테고리에든 문서를 둘 수 있었습니다. 그런데 이제는 모든 문서 주제가 단일 카테고리 아래에 있어야 하는 것 같습니다. 맞나요? 그렇다면 컨텍스트를 잃는 셈이죠. 일부(기존) 문서는 특정 그룹/카테고리(예: 스태프만 접근 가능)에 속해 있기 때문입니다.

두 접근 방식의 차이점, 왜 이 방식을 선택했는지, 그리고 레거시 플러그인과 새 플러그인 사이의 격차를 어떻게 해소할 계획인지 명확히 설명해 주실 수 있을까요? :heart:

[details="callouts"에 대한 오프톱(OT) 댓글]

HedgeDoc는 콜아웃을 지원하기 위해 다음과 같은 마크다운 확장(그들은 이를 alert areas라고 부름)를 사용합니다:

### Alert Area

:::success
Yes :tada:
:::

:::info
This is a message :mega:
:::

:::warning
Watch out :zap:
:::

:::danger
Oh No! :fire:
:::

위 코드는 다음과 같이 표시됩니다.

background-colored highlighted notes indicating severity, from green to red.
background-colored highlighted notes indicating severity, from green to red.689×354 12.1 KB
(클래스만 주어진다면 CSS로 스타일링하는 것은 꽤 쉬울 것입니다).
[/details]

게으름과 AI에 대한 오프톱(OT) 댓글

수동으로 복사-붙여넣기 하면 될 3줄의 마크다운을 위해 소비된 과도한 에너지와 물을 상상해 보세요. :slightly_frowning_face:

상대 URL과 절대 URL에 대한 오프톱(OT) 댓글

실제로 주제 URL을 복사-붙여넣는 것이 더 쉽고, 도메인을 변경하는 경우 아마도 주제 내보내기/가져오기를 수행할 것이며, 그러면 Discourse가 자동으로 도메인을 교체해 줄 것입니다.

조금 실험해 본 후, 제 (임시) 결론은 다음과 같습니다:

  1. 카테고리 설명 주제에 문서 인덱스를 제공하는 것은 유용합니다 (예: Singular Docs - Documentation - petites singularités)
  2. 최상위 Documentation 카테고리를 사용하면 하위 카테고리를 통해 문서 사이드바 인덱스를 변경할 수 있습니다 (예: "Install Ruby"는 https://ps.zoethical.org/c/docs/204에서는 “How-to Guides” 아래에, https://ps.zoethical.org/c/docs/sysadmin/205에서는 “Tips & Hints” 아래에 표시됨) 이를 통해 깔끔한 구조를 제공할 수 있습니다 (여기서 #documentation을 참조하세요. 하위 카테고리를 박스로 표시합니다)
  3. 문서 주제는 포럼의 어디에나 위치할 수 있으며, 비공개 공간도 포함됩니다 – 다만 문서 인덱스에는 그 존재가 드러나게 됩니다.
  4. 현재 사이드바는 불안정합니다:
    • 때로는 URL을 표시하고, 때로는 제목을 표시합니다
    • 때로는 접두사가 붙은 텍스트만 표시합니다
    • 로그아웃 상태에서는 일부 인덱스된 주제가 누락될 수 있습니다
  5. 레거시 문서 플러그인에서 마이그레이션할 때, 사이드바의 커스텀 섹션에서 문서 링크를 다시 생성해야 합니다 (하지만 플러그인 설정에서 /docs를 문서 카테고리로 변경하거나, 해당 카테고리로 연결되도록 /docs 영구 링크를 생성/변경하여 자동 생성할 수 있습니다)
  6. “포럼으로 돌아가기” 링크는 어색하게 느껴집니다. 문서 주제도 여전히 포럼 주제이므로, 우리는 여전히 문서 읽는 중인 포럼에 있기 때문입니다!
  7. 필터링은 아직 문서 주제가 속한 (하위) 카테고리 이름을 고려하지 않습니다.
3개의 좋아요
65

최근 업데이트로 인해 스크롤바가 있을 때 작은 UI 버그가 발생했습니다.

image
image1616×920 56.4 KB

또한 이 “필터” 검색 상자가 기본적으로 현재 카테고리 내에서 사용자 정의 검색 쿼리로 작동하도록 변경된다면(결과가 없을 때 이를 묻는 대신) 훨씬 더 효과적일 것 같습니다. 제목이 매우 짧기 때문에, 해당 분야에 익숙하지 않은 사용자가 입력하는 내용과 일치하는 결과가 나오는 경우는 대부분 없을 것입니다.

image
image1006×1066 109 KB

하지만 일반 “포럼” 사이드바가 사라지므로, 여기서 '포럼으로 돌아가기’는 일리 있는 말입니다.

1개의 좋아요
66

사이드바가 안 보인 이유가 네비게이션 메뉴 설정이 "Sidebar"가 아니라 "header dropdown"으로 되어 있었기 때문이라는 걸 알아내는 데 시간이 좀 걸렸어요. 사이드바가 안 나오는 문제를 겪고 계신 분들에게 도움이 될 수 있으니 참고해 주세요.

The image shows a computer screen with a search bar, indicating that it is a search engine interface. (Captioned by AI)
The image shows a computer screen with a search bar, indicating that it is a search engine interface. (Captioned by AI)1162×161 11.9 KB

이제 여기에서 보는 것처럼 카테고리 헤더와 하위 카테고리 상자를 추가하는 방법을 알아내려고 애를 쓰고 있습니다:

{52801E25-7954-4A36-B049-0416EB2F8EB1}
{52801E25-7954-4A36-B049-0416EB2F8EB1}1848×1135 175 KB

이 기능을 켜거나 끌 수 있는 설정을 찾을 수 없고, 아쉽게도 화면에 나타나려 하지 않습니다.
혹시 아이디어가 있으신 분이라면 조언을 구합니다.
감사합니다.

1개의 좋아요
67
4개의 좋아요
68

태그별 필터링 기능이 없는 것은 플러그인의 유용성을 크게 떨어뜨립니다. 하나의 문서가 여러 카테고리에 적용될 수 있는 커뮤니티에서는 태그별 필터링이 필수적입니다.

예를 들어, '착륙장치 조립’이라는 이름의 문서는 여러 항공기 모델에 적용될 수 있으며, 여러 태그를 포함할 수도 있습니다. 태그 필터링이 있으면 원하는 문서를 찾는 것은 매우 쉽습니다.

문서에 하나의 카테고리만 선택해야 한다면, 해당 문서가 다른 여러 카테고리에도 포함되어야 하는 경우 어떻게 해야 할까요?

태그는 이제 수동으로 생성하고 유지 관리해야 하는 자동 색인이었습니다.

이미지에는 "태그 필터"라는 제목 아래 두 목록을 비교하는 내용이 표시되어 있습니다. (AI가 캡션을 추가함)
이미지에는 "태그 필터"라는 제목 아래 두 목록을 비교하는 내용이 표시되어 있습니다. (AI가 캡션을 추가함)2000×1667 172 KB

6개의 좋아요