나의 README 가 천 줄을 처음으로 건넜을 때,나는 모두가하는 일을했다: 나는 스크롤했다. 그런 다음 나는 더 스크롤했다. "Deployment" 섹션을 찾는 네 번째 패스 주위 어딘가에,나는 포기하고 파일의 상단에 목차를 손으로 쓰기 시작했다. 그것은 내가 제목을 이름을 바꾸고,링크를 업데이트하는 것을 잊고, "Configuration" 아무것도 가리키는 README 를 발송 할 때까지 작동했다. 자신의 문서에서 깨진 페이지 내 링크는 작은 일이지만,독자에게 아무도 상점을 신경 쓰지 않는다는 것을 알려주는 일종의 작은 일입니다.
브라우저 기반 개발자 유틸리티 모음인 [Toolz.dev](/를 빌드하고, 많은 Markdown: tool guide, README 파일, 내부 specs, 그리고 지금 읽고 있는 docs를 유지관리하고 있습니다. 손으로 유지해야 하는 목차는 결국 거짓말이 될 목차입니다. 그래서 를 빌드했습니다 마크다운 TOC 생성기 매번 지루한 부분을 올바르게 수행하기 위해, 이 가이드는 앵커 링크를 구축하는 동안 앵커 링크에 대해 배운 모든 것입니다.
TL;DR: 마크다운 목차는 같은 페이지의 표제로 점프하는 링크의 중첩된 목록입니다. 링크는 각 표제가 자동 앵커 id 를 가져오기 때문에 작동하며,GitHub 가 할당하는 slug는 특정 규칙을 따릅니다: 텍스트를 소문자로 만들고,하이픈 이외의 구두점을 삭제하고,공백을 하이픈 생성기에 마크다운을 붙여넣고,포함할 표제 수준을 선택하고,목록을 복사합니다. 이 도구는 다음을 포함하여 정확한 slugs GitHub 렌더링을 계산합니다
-1중복된 제목에 접미사를 붙이므로 다시 붙여넣으면 아무 것도 깨지지 않습니다.
Markdown 목차란 무엇입니까?
마크다운의 목차는 특별한 문법이 아니다. 커먼마크 그런 구성을 정의하지 않으며,GitHub Flavored Markdown 도 마찬가지다. 모든 항목이 링크이고,모든 링크가 같은 문서 안의 앵커를 가리키는 평범한 목록이다. GitHub 같은 Markdown 렌더러가 제목을 HTML 로 바꿀 때,그 제목에도 an 을 준다 id 속성. 로 표기되는 표제 ## Getting Started 대략적으로 됩니다 <h2 id="getting-started">Getting Started</h2>. 해당 id 가 존재하면,로 작성된 링크 [Getting Started](#getting-started) 페이지를 스크롤합니다.
따라서 목차는 제목 계층 구조를 반영하기 위해 들여쓰기된 링크 모음일 뿐입니다:
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
전체 트릭은 그 예에서 한 단어에 살고 있습니다: 앵커. 앵커를 잘못 가져오면 링크가 자동으로 실패하여 아무데도 스크롤되지 않습니다. 올바르게 가져오면 콘텐츠 블록이 GitHub 에서 작동하고 대부분의 정적 사이트 생성기에서 동일한 규칙을 따르는 문서 플랫폼 내부에서 작동합니다. 어려운 부분은 목록을 작성하는 것이 아닙니다. 어려운 부분은 각 렌더러가 할당할 정확한 ID 를 예측하는 것이므로 손으로 수행하는 것은 변경되는 모든 문서에서 패배하는 게임입니다.
헤딩 앵커는 실제로 어떻게 생성됩니까?
GitHub's slug 알고리즘은 결정론적이며 외울 가치가 있습니다. 왜냐하면 일단 알고 나면 페이지의 모든 앵커를 예측할 수 있기 때문입니다. 단계는 순서대로: 표제 텍스트를 소문자로 변환하고 문자,숫자, 공백 또는 하이픈이 아닌 문자를 제거한 다음 각 공백을 하이픈으로 바꾸는 것이 전체 규칙입니다.
결과는 사람들이 여행하는 곳입니다. 같은 제목을 고려하십시오 ## Set Up & Config. 소문자는 준다 set up & config. 앰퍼샌드를 제거하면(그러나 그 주변의 공간은 그대로 두면) 제공됩니다 set up config 두 개의 공간이 있습니다 & 예전에는 그랬습니다. 공간을 하이픈으로 바꾸는 것은 생산합니다 set-up--config를,이중 하이픈으로. 그 이중 하이픈은 실수처럼 보이지만,정확히 GitHub 가 렌더링하는 것이므로,링크가 필요로 하는 것이 바로 그것입니다. A tool that "cleans up" the double hyphen would produce a link that does not resolve.
구두점이 많은 제목은 예상보다 더 많이 무너집니다. ## C++ Guide 된다 c-guide는, 더하기 기호가 모두 벗겨지고 남은 공간이 하나의 하이픈이 되기 때문입니다. ## What's New? 된다 whats-new는,아포스트로피와 물음표가 사라지기 때문에. 이모티콘과 대부분의 기호는 완전히 사라집니다. The 마크다운 TOC 생성기 이 규칙 문자를 문자에 적용하므로 slug 그것은 당신이 id GitHub가 구축 할 것이라는 것을 보여줍니다, 추측은 포함되지 않습니다.
두 제목이 같을 때 어떻게 될까요?
문서는 제목을 반복합니다. 변경 로그에는 모두 제목이 붙은 세 개의 섹션이 있을 수 있습니다 ### Fixed. 그들 모두가 slug를 생산했다면 fixed는,첫번째 링크만 동작할 것입니다. GitHub 는 중복된 번호들을 매겨서 이것을 해결합니다: 첫 번째 Fixed 얻다 fixed, 두 번째는 얻습니다 fixed-1, 세 번째는 얻습니다 fixed-2,등등 문서 순서로. 접미사는 하이픈으로 밑변 slug 뒤에 붙는다.
이것은 손으로 쓴 목차가 동기화되지 않는 가장 일반적인 이유 중 하나입니다. 이미 사용한 이름으로 두 번째 섹션을 추가하면 앵커가 조용히 됩니다 -1그리고 이전 링크는 이제 잘못된 장소 또는 전혀 아무 곳도 가리키지 않습니다. 생성기는 방출된 모든 slug를 추적하고 동일한 숫자 접미사를 적용하므로 반복되는 제목은 올바른 발생으로 연결됩니다.
도구는 어떤 종류의 제목을 읽습니까?
마크다운은 두 가지 표제 스타일을 가지고 있으며,완전한 생성기는 둘 다 읽어야 한다. 일반적인 것은 ATX 로,한 줄은 1 부터 6 까지로 시작한다 # 제목 텍스트 뒤에 오는 문자. 해시의 개수는 레벨이므로 # 는 H1 과 ###### 는 H6 입니다. 두 번째 스타일은 Setext 로,다음 줄에 H1 에 대한 등호 또는 H2 에 대한 하이픈으로 텍스트 줄에 밑줄이 그어져 있습니다:
Document Title
==============
A Section
---------
두 스타일 모두 앵커 id 로 제목을 생성하므로 둘 다 목차에 속합니다. Setext 가 있는 까다로운 부분은 하이픈 줄이 둘 중 하나를 의미할 수 있기 때문에 수평 규칙과 별도로 실제 밑줄이 그어진 제목을 알려줍니다. 생성기가 사용하는 규칙은 하이픈 밑줄이 바로 위의 줄이 빈 줄,목록 항목,블록 인용 또는 다른 블록 구성이 아닌 일반 단락 텍스트일 때만 제목으로 계산된다는 것입니다 --- 빈 줄을 그 주위에 두고 혼자 앉아 있는 것은 주제별 휴식이며 올바르게 무시됩니다.
처리할 카테고리가 하나 더 있는데,순진한 도구를 조용히 망치는 카테고리입니다: 코드 안의 표제문서. 쉘 명령을 보여주는 울타리가 있는 코드 블록이 문서에 포함되어 있다면,그 라인 중 일부는 로 시작할 것입니다 # 주석으로. 그것들은 표제가 아니며,결코 내용에 나타나서는 안됩니다. 생성기는 울타리가 있는 코드 블록 (삼중 백틱 또는 삼중 물결표로 구분된 것) 을 추적하고 아무 것도 건너뜁니다 # 그들 안에 선. 같은 쉘 코멘트 # install dependencies 예제에서는 예제에서 해당 예제가 속한 위치에 유지됩니다.In an example stays where it belong, in the example.
목차의 깊이는 어떻게 조절하나요?
H6 까지 내려가는 모든 표제를 나열한 목차는 목차가 아니라 문서의 두 번째 사본입니다. 대부분의 README 는 내용이 H2 와 H3 만 다룰 때 가장 잘 읽혀서 독자들에게 주요 섹션과 직계 자녀를 자세하게 익사시키지 않고 생성기를 사용하면 최소 및 최대 레벨을 설정할 수 있으며 해당 범위에 속하는 제목 만 포함됩니다.
여기서 미묘한 동작은 들여쓰기입니다. H2 부터 H4 까지 포함하면 유지한 가장 얕은 방향이 H2 이며,보이지 않는 H1 이 위에 있는 것처럼 들여쓰기하지 않고 왼쪽 여백에 대해 플러시 위치해야 합니다. 생성기는 실제로 포함하는 가장 얕은 방향을 기준으로 중첩 깊이를 측정하므로 H2 에서 시작하는 콘텐츠 블록은 들여쓰기 없이 시작합니다. 이는 의도적으로 보이는 목록과 첫 번째 열을 잃은 것처럼 보이는 목록의 차이입니다.
또한 목록 마커를 선택할 수 있습니다. 정렬되지 않은 목록은 모든 항목에 대해 글머리 기호를 사용하는데,이는 README 의 기존 모습입니다. 정렬된 목록은 항목 번호를 매기고 생성기는 각 중첩 수준 내에서 카운트를 다시 시작하므로 번호가 매겨진 윤곽선은 1 부터 50 까지의 직선 카운트를 세는 대신 올바르게 읽습니다. 들여쓰기는 문서의 나머지 부분에서 사용하는 내용에 따라 두 칸,네 칸 또는 탭이 될 수 있습니다.
악센트가 있는 제목과 라틴어가 아닌 제목은 어떻습니까?
모든 표제가 평범한 영어는 아니며, slug 규칙은 대처해야 합니다. GitHub는 다른 알파벳의 문자를 제거하는 대신 보관하므로 다음과 같은 표제를 사용합니다 ## Configuración 악센트가 있는 문자를 유지하고 됩니다 configuración그리고 키릴 문자나 그리스어로 된 표제어 역시 그 글자들을 유지합니다. 제거되는 것은 문자와 상관없이 문자가 아닌 구두점과 기호입니다. 생성기는 유니코드 문자나 숫자를 유효한 slug 문자로 처리하여 동일한 원리를 따르므로 다국어 문서는 빈 링크 행이 아닌 GitHub 가 렌더링하는 것과 일치하는 앵커를 생성합니다.
이것은 처음 나타나는 것보다 더 중요합니다. 스페인어,독일어 또는 일본어로 문서를 작성하는 팀은 종종 순진한 slug 도구가 제목을 사용할 수없는 앵커로 망글링한다는 것을 알게됩니다. 왜냐하면 해당 도구는 ASCII 를 가정하기 때문입니다. 번역 된 README 에서 링크가 아무 것도 가리키지 않았다면 ASCII 가 아닌 문자를 조용히 버린 slug이 거의 확실한 이유입니다. 유니코드 인식 도구로 콘텐츠 블록을 생성하면 깨진 링크의 전체 클래스가 제거되며 동일한 문서가 앵커를 잃지 않고 두 개 이상의 언어로 제목을 보유 할 수 있음을 의미합니다.
생성된 TOC와 자동 TOC는 언제 사용해야 합니까?
일부 플랫폼은 당신을 위해 목차를 구축합니다. GitLab 은 a 를 지원합니다 [[_TOC_]] 토큰,일부 위키들은 자동으로 내용 상자를 주입하고,Docusaurus 와 같은 문서화 프레임워크는 여러분이 아무것도 작성하지 않고 여러분의 표제로부터 페이지 상의 개요를 렌더링합니다. 여러분이 그 시스템들 중 하나 안에서 작업할 때,내장된 기능을 사용하는 플랫폼이 모든 렌더링에서 재생성하기 때문에,노력 없이 현재 상태를 유지합니다.
생성기는 다른 모든 곳에서 그 자리를 차지하고 "everywhere else"는 큰 장소입니다. GitHub README 는 콘텐츠 블록을 자동 생성하지 않으므로 저장소 랜딩 페이지는 파일에 커밋 된 실제 Markdown 목록이 필요합니다. 다른 것으로 변환되거나,이메일로 전송되거나,문제에 붙여 넣거나,최소한의 뷰어가 렌더링하는 Markdown 은 즉석에서 하나를 빌드 할 엔진이 없기 때문에 정적 콘텐츠 블록이 필요합니다. 아래 표는 각 접근 방식이 맞는 위치를 나타냅니다.
| 상황 | 최선의 접근법 | 왜 |
|---|---|---|
| 깃허브 README | 생성된 정적 목록 | GitHub는 제목 ID를 렌더링하지만 TOC를 자동 삽입하지는 않습니다 |
| GitLab 위키 또는 문서 | [[_TOC_]] 토큰 |
네이티브, 항상 현재 |
| Docusaurus / MkDocs 페이지 | 내장 윤곽 | Framework는 제목에서 이를 렌더링합니다 |
| 내보내기용 일반 마크다운 파일입니다 | 생성된 정적 목록 | 뷰 타임에 렌더링을 빌드할 수 없습니다 |
| 요청 설명을 발행하거나 당깁니다 | 생성된 정적 목록 | 앵커는 작동하지만 목록을 자동으로 생성하는 것은 없습니다 |
경험 법칙: Markdown을 표시하는 항목이 콘텐츠 자체를 구축할 수 있는 경우 이를 허용합니다. Markdown을 읽을 수 없는 곳에서 읽을 수 있는 경우 목록을 생성하고 커밋합니다. 형식 간에 변환할 때 HTML 변환기로 마크다운 그리고 the HTML에서 Markdown 변환기로 앵커가 왕복 여행에서 살아남기 때문에 생성된 콘텐츠 블록과 자연스럽게 쌍을 이룹니다.
이것이 Markdown 워크플로의 나머지 부분에 어떻게 적합합니까?
목차는 긴 문서를 읽을 수 있게 유지하는 한 조각이며,몇 가지 습관과 함께 가장 잘 작동합니다. 일단 제목 텍스트를 게시한 후에는 제목 텍스트를 안정적으로 유지하십시오. 왜냐하면 제목 이름을 바꾸면 slug이 변경되고 제목을 가리키는 모든 링크가 끊어지기 때문입니다. 이름을 바꾸면 기억나는 하나의 링크를 편집하는 대신 내용을 다시 생성하십시오. 이름 바꾸기는 종종 중복 접미사 번호 매기기를 파일 아래로 이동시키기 때문입니다.
구조화된 콘텐츠는 같은 제품군에 있는 다른 도구의 이점을 누릴 수 있습니다. 문서가 표 형식의 데이터에 의존할 때,the 마크다운 테이블 생성기 손으로 입력한 테이블이 거의 제대로 되지 않는 올바르게 정렬된 파이프 테이블을 빌드합니다. 깔끔한 Markdown 이 되어야 하는 지저분한 HTML 을 상속받거나 HTML 이 되어야 하는 깔끔한 Markdown 을 상속받으면 변환기는 제목 구조를 보존하면서 번역을 처리합니다. 그리고 문서의 길이 또는 키워드 균형을 감사하는 경우,the 워드 카운터 클라우드 기반의 어떤 것에도 초안을 붙여넣지 않고 숫자를 제공합니다.
모든 것이 브라우저에서 실행되며,이는 들리는 것보다 더 중요합니다. README 는 종종 공개되지 않은 기능 이름,내부 URL 또는 클라이언트 세부 정보를 포함하며,그 중 어느 것도 링크 목록을 작성하기 위해 타사 서버에 업로드해서는 안됩니다. 생성기는 클라이언트 측 JavaScript 로 Markdown 을 구문 분석하므로 문서가 기계를 떠나지 않습니다. 개발자 툴링의 개인 정보 보호가 당신이 생각하는 것이라면,쓰기에 데이터 개인 정보 보호 및 온라인 도구 로컬 처리가 올바른 기본값인 이유를 다룹니다 웹 개발자 툴킷 내가 매일 도달하는 나머지 유틸리티를 반올림합니다.
빠르게 작업한 예제
이 문서가 있다고 가정해 보겠습니다:
# Payment Service
## Getting Started
### Requirements
### Local Setup
## API Reference
### Authentication
### Errors
## Deployment
H2 에서 H3 까지 범위를 설정하고 글머리 기호 목록을 선택하고 앵커 링크를 켜두십시오. 발전기는 다음을 생성합니다:
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Local Setup](#local-setup)
- [API Reference](#api-reference)
- [Authentication](#authentication)
- [Errors](#errors)
- [Deployment](#deployment)
H1 제목은 범위 위에 위치하기 때문에 제외되고,H2 섹션은 플러시 왼쪽이며,H3 자식은 한 레벨 들여쓰기됩니다. README 의 제목 바로 아래에 블록을 붙여넣고 모든 항목이 GitHub 의 해당 섹션으로 점프합니다. 그것이 전체 작업이며,이 문장을 읽는 데 걸리는 시간에 수행되며,기계가 당신 대신 slugs를 계산했기 때문에 올바른 상태를 유지합니다.
자주 묻는 질문
Markdown 목차는 어떻게 작동합니까?
마크다운 목차는 같은 페이지 내의 표제 앵커를 가리키는 링크의 목록입니다. 마크다운 문서의 각 표제에는 자동 id 가 주어지며,로 작성된 링크가 제공됩니다 섹션 jumps to it.이 도구는 제목을 읽고 일치하는 앵커를 만들고 중첩 된 목록을 조립합니다.
앵커 링크는 어떻게 생성되나요?
앵커는 GitHub slug 규칙을 따릅니다: 제목 텍스트는 소문자로 표시되고 하이픈 이외의 구두점은 제거되며 공백은 하이픈이 됩니다. "Set Up & Config"는 id set-up-config 가 됩니다. 두 개의 제목이 동일한 slug를 생성하면 두 번째는 -1 접미사를 얻고 세 번째는 -2 등을 얻으며 GitHub 가 렌더링하는 방식과 일치합니다.
GitHub README 파일에서 작동합니까?
예. slug 알고리즘은 GitHub 가 제목 ID 를 렌더링하는 데 사용하는 것을 미러링하므로 목차 링크는 github.com 의 README 내부에서 올바르게 해결됩니다. README 를 붙여넣고 제목 수준을 선택한 다음 생성된 목록을 제목 아래에 놓습니다.
어떤 제목 레벨이 표시되는지 선택할 수 있나요?
예. 예를 들어 H2 에서 H4 까지의 최소 및 최대 레벨을 설정하고 해당 범위의 제목만 포함됩니다. 중첩 깊이는 포함된 가장 얕은 제목을 기준으로 측정되므로 윤곽선은 빈 들여쓰기가 큰 것으로 시작되지 않습니다.
코드 블록 내부의 제목이 포함되어 있습니까?
아니요. 울타리가 있는 코드 블록 (트리플 백틱 또는 트리플 타일로 구분) 안에서 #으로 시작하는 줄은 제목이 아닌 코드로 처리되므로 예제 스니펫과 셸 주석은 목차에 나타나지 않습니다.
주문한 TOC와 주문하지 않은 TOC의 차이점은 무엇입니까?
순서가 지정되지 않은 목차는 모든 항목에 하이픈과 같은 글머리 기호 표시를 사용하는 반면,순서가 지정된 목차는 각 중첩 수준 내에서 증가하는 숫자를 사용합니다. Choose ordered when readers benefit from a numbered outline,and unordered for a lighter,more conventional contents block.
도구가 Setext 제목을 지원합니까?
예. #으로 시작하는 ATX 표제와 Setext 표제를 모두 읽으며,여기서 한 줄의 텍스트에 H1 의 등호 또는 H2 의 하이픈으로 밑줄이 그어져 있습니다. 두 스타일 모두 같은 방식으로 앵커 링크로 변환됩니다.
Markdown TOC 생성기는 무료이며 비공개입니까?
예. 가입 및 제한없이 완전히 무료입니다. 모든 구문 분석은 클라이언트 측 JavaScript 를 사용하여 브라우저에서 발생하므로 붙여 넣기 한 Markdown 은 장치를 떠나지 않으며 페이지가로드되면 도구가 오프라인으로 계속 작동합니다.
