Discourse 문서

[Discourse]

이 플러그인은 실험 단계인 Doc Categories 플러그인으로 대체되어 종료됩니다. 새 플러그인이 더 이상 실험 단계로 간주되지 않을 때까지 Docs에 대한 지원을 계속합니다.

	요약	Discourse Docs는 지식 베이스 토픽을 찾고 필터링할 수 있는 기능을 제공합니다.
	저장소 링크	https://github.com/discourse/discourse-docs
	설치 가이드	Discourse에서 플러그인 설치 방법

이는 Discourse 팀이 유지 관리하는 official 플러그인이므로, 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 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 경로 이름 변경

서버에 액세스 권한이 있는 경우, app.yml에 DISCOURSE_DOCS_PATH: 환경 변수를 추가하여 /docs 링크의 경로를 변경할 수 있습니다:

변경 사항을 적용하려면 ./launcher rebuild app을 실행하거나, 환경 변수이므로 다운타임을 최소화하기 위해 ./launcher destroy app && ./launcher start app을 실행할 수 있습니다. 이에 대한 자세한 내용은 여기 - Set Environmental Variables 에서 확인할 수 있습니다.

사이트 표시 텍스트도 일치하도록 변경하는 것이 좋습니다. /admin/customize/site_texts 페이지에서 'docs’의 모든 인스턴스를 검색할 수 있지만, 주요 항목은 다음과 같습니다:

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

우리가 호스팅하고 있나요? /docs 경로 이름 변경은 Enterprise 플랜에서만 사용할 수 있습니다. 더 알고 싶으시다면 우리에게 연락해 주세요.

개발 역사

Docs 플러그인은 Knowledge Explorer 테마 컴포넌트의 연속이었습니다.

[Hyan]

디스커스 커뮤니티 여러분,

스펙을 실행하는 중 아래 오류가 발생했습니다. 저는 어떤 파일도 수정하지 않았습니다. 이 오류를 무시해도 될까요?

➜  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처럼요. 이 두 버전의 페이지가 구글 알고리즘에서 서로를 잠식(cannibalize)하지는 않을까 궁금하네요.

[sam (Sam Saffron)]

네, 물론이죠. 거기에 대해 뭔가 해야 합니다.

[Hyan]

죄송합니다 @JammyDodger, 요즘 Spec을 실행할 기회가 없었습니다. 요즘은 Discourse Docs 관련 작업보다는 다른 업무에 집중하고 있습니다. 기회가 되면 알려드리겠습니다.

[martyn_thomas]

햄버거 메뉴의 Docs 옆 아이콘을 링크/체인에서 다른 것으로 변경할 방법이 있을까요?

[martyn_thomas]

이 플러그인은 모든 문서 카테고리를 한곳에 모아둘 수 있어 매우 좋습니다. 덕분에 카테고리 목록에 중복으로 나열할 필요가 없게 되었습니다(고마워요, Discourse Category Hider). 하지만 문제가 하나 발견되었습니다.

Docs 플러그인 화면에서는 기존 문서를 편집하거나 새 문서를 생성할 수 없습니다. 즉, 편집하려면 원래 카테고리로 가서 해당 주제/문서를 찾아야 합니다… 결국 문서가 여러 곳에 접근 가능해야 한다는 뜻입니다.

Docs 플러그인 내에서 주제/문서 편집을 활성화할 수 있는 방법이 있을까요? (해당 사용자 그룹에 속한 사용자의 경우)

[Moin]

@martyn_thomas

편집하려면 원래 카테고리로 가서 해당 주제/문서를 찾아야 합니다.

하단에 있는 “이 주제에 대한 토론 보기” 링크를 통해 해당 주제로 이동하여 편집하는 방식이 가능한가요?

[digitaldominica]

안녕하세요, 정말 짜증나는 문제가 있어서 왜 이런 일이 일어나는지 모르겠습니다.

문서를 생성하면 문서 영역으로 이동하여 정상적으로 작동합니다. 하지만 문서가 어떤 방식으로든 수정되면, 문서 목록의 주제 문서 레이아웃이 클릭 시 실제 문서 레이아웃을 표시하지 않고 기본 Discourse 주제 레이아웃으로 되돌아갑니다.

몇 분 후면 다시 주제 문서 레이아웃으로 돌아와서 정상적으로 보인다는 걸 알아차렸는데, 이런 현상을 일으킬 수 있는 원인이 있을까요?

참고로 “Topic Thumbnails” 테마 컴포넌트도 사용 중이며, 문서 썸네일 모드를 "list"로 설정해 두었습니다.

[digitaldominica]

문제를 찾았어요. Topic List Excerpts 또는 Topic lists Thumbnails 테마 구성 요소를 사용하면 클릭 가능한 링크가 KB 문서의 docs?topic=xxx가 아니라 discourse 주제 페이지를 가리키고 있어서 discourse 주제로 리디렉션되고 있네요.

@sam 님, 문서의 URL 경로를 유지하는 방법이 있을까요? 아니면 @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)]

Docs의 기본 검색 순서가 "관련도"가 아니라 "활동 날짜"라는 사실에 놀랐습니다.

관련도로 검색할 수 있을까요?

[thaidb]

오늘 Docs 카테고리에 몇 가지 주제를 게시했는데, Docs 페이지에 해당 주제가 표시되지 않습니다. Docs 플러그인을 끄고 다시 켜 보았지만, 여전히 해당 주제가 표시되지 않습니다.
감사합니다!