TOC อัตโนมัติในรูปแบบ GitHub-Markdown

มันเป็นไปได้ในการสร้างตารางอัตโนมัติสารบัญใช้Github รส Markdown ?

ฉันสร้างสองตัวเลือกเพื่อสร้าง toc สำหรับ github-flavored-markdown:

เครื่องมือบรรทัดคำสั่ง DocToc ( ต้นฉบับ ) ต้องการnode.js

npm install doctoc

npx doctoc . เพื่อเพิ่มสารบัญลงในไฟล์ markdown ทั้งหมดในไดเรกทอรีย่อยปัจจุบันและทั้งหมด

DocToc WebApp

หากคุณต้องการลองออนไลน์เป็นครั้งแรกให้ไปที่ไซต์doctocวางลิงก์ของหน้า markdown และจะสร้างสารบัญที่คุณสามารถแทรกที่ด้านบนของไฟล์ markdown ของคุณ

Github Wikis และ Anchors

ดังที่ Matthew Flaschen ชี้ให้เห็นในความคิดเห็นด้านล่างสำหรับหน้าวิกิของ GitHub ก่อนหน้านี้ไม่ได้สร้างจุดยึดที่doctocขึ้นอยู่กับ

UPDATE: อย่างไรก็ตามพวกเขาแก้ไขปัญหานี้

หน้า GitHub (ซึ่งโดยทั่วไปแล้วเป็นเสื้อคลุมสำหรับ Jekyll) ดูเหมือนจะใช้ kramdownซึ่งใช้งาน Maruku ทั้งหมดและดังนั้นจึงมีการสนับสนุนสารบัญที่สร้างขึ้นโดยอัตโนมัติผ่านtocแอตทริบิวต์:

* auto-gen TOC:
{:toc}

บรรทัดแรกเพิ่งเริ่มรายการที่ไม่มีการเรียงลำดับและถูกโยนทิ้งไปจริง ๆ

สิ่งนี้ส่งผลให้เกิดชุดของรายการที่ไม่เรียงลำดับโดยใช้ส่วนหัวในเอกสาร

หมายเหตุ:สิ่งนี้ควรใช้กับหน้า GitHub ไม่ใช่ GitHub Flavoured Markdown (GFM) ตามที่ใช้ในความคิดเห็นหรือหน้า wiki AFAIK ไม่มีวิธีแก้ปัญหาสำหรับสิ่งนั้น

หากคุณแก้ไขไฟล์ Markdown กับกลุ่มคุณสามารถลองนี้ปลั๊กอินเป็นกลุ่ม-markdown-toc

การใช้งานนั้นง่ายเพียงเลื่อนเคอร์เซอร์ไปยังตำแหน่งที่คุณต้องการผนวกสารบัญและใช้:GenTocGFMงานเสร็จ!

ภาพหน้าจอ:

คุณสมบัติ:

1. สร้าง toc สำหรับไฟล์ Markdown (รองรับการ Markdown รส GitHub และ Redcarpet)

2. อัพเดต toc ที่มีอยู่

3. toc update อัตโนมัติเมื่อบันทึก

ไม่ใช่อัตโนมัติ แต่ใช้ Notepad ++ นิพจน์ทั่วไป:

แทนที่ทั้งหมดก่อนโดยที่สอง (ลบบรรทัดทั้งหมดที่ไม่มีส่วนหัว)

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

จากนั้น (แปลงส่วนหัว III เป็นช่องว่าง)

-##
        -

จากนั้น (แปลงส่วนหัว II เป็นช่องว่าง)

-#
    -

จากนั้น (ลบตัวอักษรที่ไม่ได้ใช้ตอนต้นและตอนท้ายของลิงค์ชื่อ)

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

จากนั้น (แปลงโทเค็นตัวพิมพ์เล็กและเส้นประล่าสุดแทนช่องว่าง)

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

ลบปอนด์สุดท้ายที่ไม่ได้ใช้และขีดกลางเริ่มต้น:

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

ลบตัวอักษรที่ไม่มีประโยชน์ในลิงก์:

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

และในที่สุดก็เพิ่มวงเล็บรอบ ๆ ลิงก์สุดท้าย:

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

และvoilà! คุณสามารถใส่มันลงไปในแมโครส่วนกลางได้ถ้าคุณทำซ้ำเวลาพอ

ไม่สามารถทำได้ยกเว้นการแก้ไขปัญหาที่เสนอ

ฉันเสนอ Kramdown TOC extension และความเป็นไปได้อื่น ๆ เพื่อ support@github.com และSteven! Ragnarökตอบด้วยตามปกติ:

ขอบคุณสำหรับคำแนะนำและลิงค์ ฉันจะเพิ่มลงในรายการคำขอคุณลักษณะภายในของเราเพื่อให้ทีมดู

ลองโหวตคำถามนี้จนกว่ามันจะเกิดขึ้น

วิธีแก้ปัญหาก็คือการใช้ Asciidoc แทน Markdown, ซึ่งจะทำให้สารบัญ ฉันได้เปลี่ยนวิธีการนี้เป็นเนื้อหาของฉันในปัจจุบัน

Github Flavoured Markdown ใช้ RedCarpet เป็นเอ็นจิ้น Markdown จากRepC RedCarpet :

: with_toc_data - เพิ่มจุดยึด HTML ให้กับส่วนหัวแต่ละส่วนใน HTML ออกเพื่อให้สามารถเชื่อมโยงไปยังแต่ละส่วนได้

ดูเหมือนว่าคุณจะต้องอยู่ในระดับ renderer เพื่อตั้งค่าสถานะนี้ซึ่งไม่สามารถทำได้บน Github อย่างไรก็ตามการอัปเดตล่าสุดไปยังหน้า Github ดูเหมือนว่าจะเปิดใช้การยึดอัตโนมัติสำหรับส่วนหัวสร้างส่วนหัวที่ลิงก์ได้ ไม่ตรงตามที่คุณต้องการ แต่มันอาจช่วยให้คุณสร้าง TOC สำหรับเอกสารของคุณได้ง่ายขึ้นเล็กน้อย (แม้ว่าจะด้วยตนเอง)

วิธีที่สะดวกมากที่จะบรรลุสารบัญสำหรับไฟล์ mardown เมื่อทำงานกับ Visual Studio รหัสคือการขยายMarkdown-TOC

มันสามารถเพิ่ม toc ไปยังไฟล์ markdown ที่มีอยู่และยังทำให้ toc ทันสมัยในการบันทึก

เป็นไปได้ที่จะสร้างเว็บเพจโดยอัตโนมัติด้วยhttp://documentup.com/จากREADME.mdไฟล์ มันไม่ได้สร้าง TOC แต่สำหรับหลาย ๆ คนมันอาจจะแก้ปัญหาสาเหตุที่ต้องการสร้าง TOC

ทางเลือกอื่นในการ Documentup คือ Flatdoc: http://ricostacruz.com/flatdoc/

Gitdownเป็นตัวประมวลผลล่วงหน้า markdown สำหรับ Github

การใช้ Gitdown คุณสามารถ:

• สร้างสารบัญ
• ค้นหา URL ที่ไม่ทำงานและตัวระบุส่วน
• รวมตัวแปร
• รวมไฟล์
• รับขนาดไฟล์
• สร้างป้าย
• วันที่พิมพ์
• พิมพ์ข้อมูลเกี่ยวกับพื้นที่เก็บข้อมูลของตัวเอง

Gitdown คล่องตัวงานทั่วไปที่เกี่ยวข้องกับการบำรุงรักษาหน้าเอกสารสำหรับที่เก็บ GitHub

ใช้มันตรงไปตรงมา:

var Gitdown = require('gitdown');

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

คุณสามารถให้มันเป็นสคริปต์แยกต่างหากหรือให้เป็นส่วนหนึ่งของรูทีนการสร้างสคริปต์ (เช่นอึก )

ใช้coryfklein / doctocซึ่งเป็นทางแยกของthlorenz / doctocที่ไม่เพิ่ม "ที่สร้างขึ้นด้วย DocToc " ลงในสารบัญทั้งหมด

npm install -g coryfklein/doctoc

เพื่อนร่วมงานของฉัน @schmiedc และฉันได้สร้างสคริปต์ GreaseMonkeyที่ติดตั้งTOCปุ่มใหม่ทางซ้ายของh1ปุ่มซึ่งใช้markdown-jsไลบรารีที่ยอดเยี่ยมในการเพิ่ม / รีเฟรชสารบัญ

ข้อได้เปรียบเหนือโซลูชันเช่น doctoc คือมันรวมเข้ากับวิกิแก้ไขของ GitHub และไม่ต้องการให้ผู้ใช้ทำงานบนบรรทัดคำสั่ง (และต้องการให้ผู้ใช้ติดตั้งเครื่องมือเช่น node.js ) ใน Chrome ทำงานได้โดยการลากและวางลงในหน้าส่วนขยายใน Firefox คุณจะต้องติดตั้งส่วนขยาย GreaseMonkey

มันจะทำงานร่วมกับ markdown ธรรมดา (เช่นมันไม่ได้จัดการบล็อกรหัสอย่างถูกต้องเนื่องจากเป็นส่วนขยาย GitHub เพื่อ markdown) ผลงานยินดีต้อนรับ

นี่ไม่ใช่คำตอบที่ตรงกับคำถามนี้เนื่องจากมีคนจำนวนมากที่ให้การแก้ไขปัญหา ฉันไม่คิดว่าการสร้าง TOC นั้นได้รับการสนับสนุนอย่างเป็นทางการจาก Github จนถึงปัจจุบัน หากคุณต้องการที่จะทำให้ GitHub สารบัญบนหน้าตัวอย่าง GFM ของพวกเขาโดยอัตโนมัติโปรดเข้าร่วมการอภิปรายอย่างเป็นทางการในปัญหาคุณลักษณะคำขอ

ขณะนี้มันเป็นไปไม่ได้โดยใช้ไวยากรณ์ markdown (ดูอย่างต่อเนื่องการอภิปรายที่ GitHub ) แต่คุณสามารถใช้เครื่องมือภายนอกบางอย่างเช่น:

• ตารางสร้างเนื้อหาออนไลน์( raychenon / play-of-table-of-content )
• arthurhammer / github-toc - ส่วนขยายเบราว์เซอร์ที่เพิ่มสารบัญลงใน repos ของ GitHub

หรือใช้AsciiDocแทน (เช่นREADME.adoc) เช่น

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

## A

### A2

## B

### B2

ตามที่แนะนำในความคิดเห็นนี้ ตรวจสอบการสาธิตที่นี่

สำหรับAtom Textititor Atomของ Githubลองดูปลั๊กอินที่น่าประทับใจนี้ (หรือ "แพ็คเกจ" ใน Atom-lingo) ซึ่งสร้าง"TOC (สารบัญ) ของพาดหัวจากการแยกวิเคราะห์" :

markdown-toc

เมื่อติดตั้งเป็นแพ็คเกจ Atom คุณสามารถใช้ทางลัดctrl-alt-cเพื่อแทรก TOC ตามโครงสร้าง markdown-doc ของคุณที่ตำแหน่งเคอร์เซอร์ปัจจุบัน ...

ภาพหน้าจอ:

Atom Keybindings

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 Action ที่ทำสิ่งนี้สำเร็จ:

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