깃 허브 맛 마크 다운의 자동 TOC

Github Flavored Markdown을 사용하여 자동 목차를 생성 할 수 있습니까?

github-flavored-markdown에 대한 목차를 생성하는 두 가지 옵션을 만들었습니다.

DocToc 명령 행 도구 ( source )에는 node.js

npm install doctoc

npx doctoc . 현재 및 모든 서브 디렉토리의 모든 마크 다운 파일에 목차를 추가합니다.

DocToc WebApp

먼저 온라인으로 시도하려면 doctoc 사이트 로 이동 하여 마크 다운 페이지의 링크를 붙여 넣으면 마크 다운 파일 맨 위에 삽입 할 수있는 목차가 생성됩니다.

Github Wiki 및 앵커

Matthew Flaschen이 아래 주석에서 지적했듯이 GitHub의 Wiki 페이지는 이전에 doctoc의존 하는 앵커를 생성하지 않았습니다 .

업데이트 : 그러나 그들은 이 문제를 해결했습니다 .

GitHub Pages (기본적으로 Jekyll의 래퍼) 는 모든 Maruku 를 구현 하는 kramdown을 사용하는 것으로 보이며 , 따라서 속성을 통해 자동으로 생성 된 목차 를 지원 toc합니다.

* auto-gen TOC:
{:toc}

첫 번째 줄은 순서가없는 목록을 시작하고 실제로 버려집니다.

이로 인해 문서의 헤더를 사용하여 중첩 된 순서가없는 목록이 생성됩니다.

참고 : 이것은 주석 또는 위키 페이지에서 사용되는 GitHub Flavored Markdown (GFM)이 아닌 GitHub 페이지에서 작동합니다. AFAIK 솔루션이 존재하지 않습니다.

Vim을 사용하여 Markdown 파일을 편집하는 경우이 플러그인 vim-markdown-toc를 사용해보십시오 .

사용법은 간단합니다. 커서를 목차를 추가 할 곳으로 옮기고 실행하십시오 :GenTocGFM!

스크린 샷 :

풍모:

1. 마크 다운 파일에 대한 toc를 생성하십시오. (깃 허브 풍미 마크 다운 및 레드 카펫 지원)

2. 기존 목차를 업데이트합니다.

3. 저장시 자동 업데이트 목차.

자동은 아니지만 메모장 ++ 정규 표현식을 사용합니다.

첫 번째를 모두 두 번째로 바꾸십시오 (헤더가없는 모든 줄을 제거하십시오)

^##(#?)(#?)(.*?)$(.|\r|\n)*?(?=^##|\z)
-\1\2 [\3](#\3)\n

그런 다음 (헤더 III을 공백으로 변환)

-##
        -

그런 다음 (헤더 II를 공백으로 변환)

-#
    -

그런 다음 (링크 제목의 시작과 끝에서 사용하지 않는 문자를 제거하십시오)

\[ *((?:(?![ .:#!\?;]*\])[^#])*)[ #:!\?;]*\]
[\1]

그런 다음 (마지막 토큰을 공백 대신 소문자 및 대시로 변환)

\]([^ \r\n]*) ([^\r\n ]*)
]\L\1-\2

사용하지 않은 최종 파운드와 초기 대시를 제거하십시오.

(?:()[-:;!\?#]+$|(\]#)-)
\1\2

링크에서 쓸모없는 문자를 제거하십시오.

(\].*?)(?:\(|\))
\1

마지막으로 마지막 링크 주위에 괄호를 추가하십시오.

\](?!\()(.*?)$
\]\(\1\)

그리고 voilà! 충분한 시간을 반복하면 전역 매크로에 넣을 수도 있습니다.

제안 된 해결 방법을 제외하고는 불가능합니다.

내가 제안 support@github.com과에 Kramdown TOC 확장 및 다른 가능성을 스티븐! Ragnarök 는 평소와 같이 대답했습니다.

제안과 링크에 감사드립니다. 팀이 볼 수 있도록 내부 기능 요청 목록에 추가하겠습니다.

이 질문이 일어날 때까지이 질문을 찬성하자.

또 다른 해결 방법은 TOC를 렌더링하는 Markdown 대신 Asciidoc을 사용하는 것입니다 . 요즘 내 콘텐츠에 대해이 접근법으로 옮겼습니다.

Github Flavored Markdown은 RedCarpet을 Markdown 엔진으로 사용합니다. 로부터 RedCarpet의 REPO :

: with_toc_data-출력 HTML의 각 헤더에 HTML 앵커를 추가하여 각 섹션에 연결할 수 있습니다.

이 플래그를 설정하려면 렌더러 수준에 도달해야 할 것으로 보입니다 .Github에서는 분명히 불가능합니다. 그러나 Github Pages 의 최신 업데이트 에서는 헤더에 자동 앵커가 설정되어 링크 가능한 제목이 생성되는 것 같습니다. 정확히 원하는 것은 아니지만 문서의 TOC를 조금 더 쉽게 만드는 데 도움이 될 수 있습니다 (수동이지만).

Visual Studio Code로 작업 할 때 mardown 파일의 목차를 얻는 매우 편리한 방법은 확장명 Markdown-TOC 입니다.

기존 마크 다운 파일에 toc를 추가하고 저장할 때 toc를 최신 상태로 유지할 수도 있습니다.

파일 에서 http://documentup.com/ 을 사용하여 웹 페이지를 자동으로 생성 할 수 README.md있습니다. TOC를 생성하는 것은 아니지만 많은 경우 TOC를 생성하려는 이유를 해결할 수 있습니다.

Documentup의 또 다른 대안은 Flatdoc입니다. http://ricostacruz.com/flatdoc/

Gitdown 은 Github의 마크 다운 프리 프로세서입니다.

Gitdown을 사용하면 다음을 수행 할 수 있습니다.

• 목차 생성
• 죽은 URL 및 조각 식별자 찾기
• 변수 포함
• 파일 포함
• 파일 크기 얻기
• 배지 생성
• 인쇄 일
• 저장소 자체에 대한 정보를 인쇄하십시오.

Gitdown은 GitHub 리포지토리의 문서 페이지 유지 관리와 관련된 일반적인 작업을 간소화합니다.

그것을 사용하는 것은 간단합니다 :

var Gitdown = require('gitdown');

Gitdown
    // Gitdown flavored markdown.
    .read('.gitdown/README.md')
    // GitHub compatible markdown.
    .write('README.md');

별도의 스크립트로 사용하거나 빌드 스크립트 루틴 (예 : Gulp )의 일부로 사용할 수 있습니다 .

사용 coryfklein / doctoc 의 포크 thlorenz / doctoc "추가하지 않는 생성 DocToc 내용의 모든 테이블에".

npm install -g coryfklein/doctoc

저의 동료 @schmiedc와 저는 GreaseMonkey 스크립트 를 작성 하여 훌륭한 라이브러리를 사용하여 목차를 추가 / 갱신하는 TOC버튼 왼쪽에 새 버튼 을 설치했습니다 .h1markdown-js

doctoc과 같은 솔루션의 장점은 GitHub의 wiki 편집기에 통합되어 있으며 사용자가 명령 줄에서 작업 할 필요가 없으며 사용자가와 같은 도구를 설치해야한다는 것 node.js입니다. Chrome에서는 Extensions 페이지로 끌어서 놓아 작동합니다. Firefox에서는 GreaseMonkey 확장을 설치해야합니다.

일반 마크 다운과 함께 작동합니다 (즉, 마크 다운에 대한 GitHub 확장이므로 코드 블록을 올바르게 처리하지 못합니다). 기부를 환영합니다.

많은 사람들이 해결 방법을 제공했기 때문에 이것은이 질문에 대한 직접적인 대답이 아닙니다. TOC 생성이 공식적으로 아직 Github에 의해 지원되지 않았다고 생각합니다. GitHub가 GFM 미리보기 페이지에서 목차를 자동으로 렌더링하도록하려면 공식 기능 요청 문제 에 대한 토론에 참여하십시오 .

현재 그건 불가능 인하 구문 (진행 참조하여 GitHub의에서 토론을 하지만 당신과 같은 일부 외부 도구를 사용할 수 있습니다) :

• 온라인 목차 생성기 ( raychenon / play-table-of-contents )
• arthurhammer / github-toc-GitHub 저장소에 목차 를 추가하는 브라우저 확장

또는 사용 AsciiDoc대신 (예를 들어 README.adoc), 예를 들어,

:toc: macro
:toc-title:
:toclevels: 99
# Title

## A

### A2

## B

### B2

이 의견 에서 제안한대로 . 여기서 데모를 확인 하십시오 .

대한 Github에서의 문서 편집기 아톰 생성이 멋진 플러그인 (또는 "패키지"아톰 용어에서), 체크 아웃 "구문 분석 인하 헤드 라인의 TOC (목차)" 파일 :

마크 다운

Atom 패키지로 설치되면 바로 가기를 사용할 수 있습니다 ctrl-alt-c 를 하여 현재 커서 위치에서 마크 다운 문서 구조를 기반으로 TOC를 삽입 .

스크린 샷 :

원자 키 바인딩

markdown-toc는 Atom에서 플러그인을 제어하기위한 다음과 같은 기본 키 바인딩을 제공합니다.

• ctrl-alt-c => 커서 위치에 TOC 생성
• ctrl-alt-u => TOC 업데이트
• ctrl-alt-r => TOC 삭제

플러그인 기능 (프로젝트의 README에서)

• 앵커 태그를 통한 자동 링크, ​​예 : # A 1→#a-1
• 심층 제어 [1-6] depthFrom:1및depthTo:6
• 링크를 사용하거나 사용하지 않도록 설정 withLinks:1
• 저장시 목록 새로 고침 updateOnSave:1
• 와 함께 정렬 된 목록 (1. ..., 2. ...) 사용 orderedList:0

여기에 오늘 함께 던진 쉘 스크립트가 있습니다. 필요에 따라 조정해야 할 수도 있지만 좋은 출발점이되어야합니다.

cat README.md \
    | sed -e '/```/ r pf' -e '/```/,/```/d' \
    | grep "^#" \
    | tail -n +2 \
    | tr -d '`' \
    | sed 's/# \([a-zA-Z0-9`. -]\+\)/- [\1](#\L\1)/' \
    | awk -F'(' '{for(i=2;i<=NF;i++)if(i==2)gsub(" ","-",$i);}1' OFS='(' \
    | sed 's/^####/      /' \
    | sed 's/^###/    /' \
    | sed 's/^##/  /' \
    | sed 's/^#//'

누구든지 최종 교체를 수행하는 더 좋은 방법을 알고 있다면 의견을 추가하십시오. 나는 여러 가지 일을 시도했지만 어떤 것에도 만족하지 않았기 때문에 나는 그것을 무차별하게 강요했습니다.

이제 이것을 수행하는 GitHub 액션이 있습니다.

https://github.com/marketplace/actions/toc-generator

1. TOC (옵션)의 위치를 ​​지정하십시오. 예 : README.md

<!-- START doctoc -->
<!-- END doctoc -->

2. 설정 워크 플로우 예 .github/workflows/toc.yml

on: push
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v2

다른 답변의 대부분은 도구를 설치해야합니다. 빠르고 쉬운 온라인 솔루션 https://imthenachoman.github.io/nGitHubTOC을 찾았습니다 .

모든 마크 다운 입력에 대해 목차 출력이 생성됩니다. 최소 및 최대 제목 수준을 지정할 수 있습니다.

소스 코드는 https://github.com/imthenachoman/nGitHubTOC에 있습니다.