🇨🇳 DiscoTOC 자동 콘텐츠 목차

[honeymoose]

	개요	DiscoTOC는 테마에 대해 버튼 한 번으로 목차(TOC)를 생성할 수 있도록 해줍니다.
	미리보기	Beginner's guide to using Discourse Themes (링크는 새 탭에서 방문해주세요)
	저장소 링크	https://github.com/discourse/DiscoTOC
	Discourse 테마에 대해 잘 모르시나요?	공식 웹사이트에서 Discourse 테마 사용 초보 가이드를 참고하세요.

예시

데스크톱

모바일

기능

toc = table of contents (목차)

• 메뉴 상단의 설정 버튼을 통해 현재 콘텐츠 상태에 맞춰 버튼 한 번으로 TOC 목록을 생성합니다.
• TOC는 페이지에 항상 표시됩니다. 콘텐츠 스크롤과 토픽 내 링크가 동기화됩니다.
• 현재 페이지의 섹션을 스크롤할 때, 해당 섹션의 TOC 항목이 하이라이트(초록색)로 표시됩니다.
• 제목에 속성을 추가할 수 있습니다(다른 토픽/포스트에서 특정 콘텐츠로 링크할 수 있음).
• TOC의 섹션 링크를 클릭하면 브라우저가 본문 콘텐츠의 해당 위치로 이동합니다(스크롤 동기화).
• 각 제목에 복사 가능한 링크를 추가할 수 있습니다(원하는 경우에만).
• RTL(오른쪽에서 왼쪽으로 읽는 언어) 지원
• 현재 사용 중인 색상 테마를 기반으로 한 색상 스킴 적용

작동 원리

기본적으로 현재 콘텐츠의 제목은 TOC로 표시됩니다(composer 버튼으로 이 작업을 수행합니다). 또한 현재 토픽이 해당 태그를 가지고 있다면, 이는 제목의 계층 구조에 따라 TOC로 변환됩니다. 모든 콘텐츠 제목은 TOC로 변환되어야 하므로 MD 파일의 제목 설정이 정확해야 하며, 제목 계층 설정에 오류가 있으면 변환 결과에도 오류가 발생합니다.

# heading 1
## heading 2
### heading 3
#### heading 4
##### heading 5
###### heading 6

계층 구조는 자유롭게 조정할 수 있지만, 계층의 정확성을 반드시 유지해야 합니다.

# heading 2 
## heading 3
## heading 3
### heading 4
## heading 3
# heading 2

etc...

링크가 정상적으로 작동하려면 모든 제목에는 Id 속성이 필요합니다.

이 컴포넌트는 제목의 Id를 자동으로 검증합니다. Id가 존재하면 컴포넌트가 더 효율적으로 실행됩니다. 또한 Id는 수동으로 토픽을 생성할 때에도 유용합니다.

제목에 Id가 없다면, 이 컴포넌트는 제목의 내용을 기반으로 Id를 자동으로 생성합니다(불필요한 문자는 자동으로 무시됩니다).

위의 모든 작업이 완료되면, TOC는 제목을 기반으로 본문으로 연결되는 링크를 생성합니다. 아래 그림과 같습니다:

설정

이 컴포넌트는 TOC 아이콘(이 이미지는 후속 설정에서 사용되며, 공식적으로 이 아이콘을 수정하는 것은 권장되지 않음)에 대한 설정만 하나 있습니다.

번역 및 현지화

이 컴포넌트는 번역이 필요한 내용이 매우 적으며, 아래 3개 필드만 번역하면 됩니다.

table_of_contents: "table of contents (목차)"

이것은 모바일에서 TOC를 열 때 표시됩니다.

insert_table_of_contents: "Insert table of contents (목차 삽입)"

이것은 목차가 토픽 페이지에 삽입될 때 표시됩니다.

topic_will_contain_a_table_of_contents: "This topic will contain a table of contents (이 토픽에는 목차가 포함됩니다)"

이 내용은 토픽 내용을 편집할 때, 오른쪽의 미리보기 영역에 표시됩니다.

제목 생성 방법

1. 콘텐츠의 제목을 생성할 때 올바른 구문을 사용해야 합니다.
2. 페이지의 메뉴 옵션을 클릭합니다(이 옵션은 일반 토픽과 포스트에서만 표시되며, 답변이나 개인 메시지는 해당되지 않습니다).
3. 토픽 페이지에 삽입합니다.

TOC 사용 시 읽기 진행률 위젯은 어떻게 되는가

페이지에서 읽기 진행률과 TOC를 동시에 표시할 수 없다는 것을 아실 수 있습니다.

공식 솔루션은 다음과 같습니다. 첫 번째 포스트를 읽는 동안 TOC가 존재하면, 페이지에는 TOC만 표시되고 읽기 진행률 위젯은 표시되지 않습니다.

첫 번째 포스트를 넘어 읽을 때, TOC는 표시되지 않고 대신 전체 콘텐츠의 읽기 진행률 표시줄이 표시됩니다.

간단히 말해, TOC는 첫 번째 포스트에만 적용되며, 이후 포스트에는 읽기 진행률 표시줄이 사용됩니다.

모바일과 데스크톱 앱의 표시 방식은 동일합니다.

이 컴포넌트 사용 시 발생할 수 있는 문제

작성자 및 공식 발표에 따르면, 이 컴포넌트를 사용하면서 현재까지 문제가 발생하지 않았습니다.

모든 콘텐츠 표시는 클라이언트 측에서 수행됩니다(전문 용어로 표현하면 프론트엔드에서 처리됨). 따라서 백엔드 데이터 제공에는 아무런 영향이 없습니다.

이 컴포넌트를 비활성화하면 모든 콘텐츠가 원래 상태로 복원됩니다.

사용 제한

이 컴포넌트는 표준 테마 레이아웃을 사용합니다.

사용 중인 레이아웃이 제목 사용법을 수정한 경우, 이 TOC 컴포넌트는 정상적으로 작동하지 않을 수 있습니다.

예를 들어, Vincent 테마를 사용하는 경우 이 컴포넌트는 정상적으로 작동하지 않는 것으로 알려져 있습니다.

인기 있는 테마에 대한 지원은 이 공식 플러그인의 다음 고려 사항입니다.

개발자

공식 작성자는 Greg Franko의 tocify.js 라이브러리를 기반으로 개발했습니다.

하지만 안타깝게도 이 라이브러리는 오랫동안 업데이트되지 않아, 작성자는 불필요한 내용과 기능이 없거나 코드 중 불필요한 부분을 제거하고 관련 기능을 Discourse에 통합했습니다.

전체 컴포넌트의 크기는 약 4kb입니다(gzip 압축 기준).

작성자는 @erlend_sh 님의 훌륭한 조언과 @david 님의 번역 작업에 감사의 뜻을 전합니다.

개선 사항(TODO)

• 편집 시 TOC를 실시간으로 비교 표시(리소스 소모가 매우 클 수 있음)
• 주요 테마에서 TOC 표시 지원
• 제목의 링크 버튼을 클릭할 때 자동으로 클립보드에 복사.

이 버전의 릴리스에 대해 작성자는 다음과 같이 밝혔습니다: 이 릴리스는 아직 초기 단계이며, 이 컴포넌트에 대한 문제점이나 제안, 개선 사항이 있다면 원작자에게 직접 연락해 주시기 바랍니다.

공식적인 이 컴포넌트 설명, 링크 및 토론은 다음 페이지를 참고하세요: DiscoTOC - automatic table of contents

기술 지원 (중국어)

기타 문의 사항이나 도움이 필요하신 경우, 당사 웹사이트(중국어)를 방문하세요: iSharkFly - 飞鲨