TOC otomatis dalam github-flavoured-markdown

Apakah mungkin membuat Daftar Isi otomatis menggunakan Github Flavoured Markdown ?

Saya membuat dua opsi untuk menghasilkan toc untuk github-flavored-markdown:

Alat Baris Perintah DocToc ( sumber ) membutuhkan node.js

npm install doctoc

npx doctoc . untuk menambahkan daftar isi ke semua file penurunan harga di direktori saat ini dan semua.

DocToc WebApp

Jika Anda ingin mencobanya online terlebih dahulu, buka situs doctoc , rekatkan tautan laman penurunan harga dan itu akan menghasilkan daftar isi yang dapat Anda masukkan di bagian atas file penurunan harga Anda.

Github Wikis and Anchors

Seperti yang ditunjukkan Matthew Flaschen dalam komentar di bawah, untuk halaman wiki-nya, GitHub sebelumnya tidak menghasilkan jangkar itu doctoc bergantung padanya.

UPDATE: Namun, mereka memperbaiki masalah ini .

GitHub Pages (yang pada dasarnya adalah pembungkus untuk Jekyll) tampaknya menggunakan kramdown , yang mengimplementasikan semua Maruku , dan karenanya memiliki dukungan untuk daftar isi yang dihasilkan secara otomatis melalui tocatribut:

* auto-gen TOC:
{:toc}

Baris pertama baru saja memulai daftar tidak terurut dan sebenarnya dibuang.

Ini menghasilkan kumpulan daftar unordered bersarang, menggunakan header dalam dokumen.

Catatan: ini harus bekerja untuk Halaman GitHub, bukan GitHub Flavoured Markdown (GFM) seperti yang digunakan dalam halaman komentar atau halaman wiki. AFAIK solusi tidak ada untuk itu.

Jika Anda mengedit file Penurunan harga dengan Vim, Anda dapat mencoba plugin ini vim-markdown-toc .

Penggunaannya sederhana, cukup gerakkan kursor ke tempat Anda ingin menambahkan Daftar Isi dan jalankan :GenTocGFM , selesai!

Tangkapan layar:

Fitur:

1. Hasilkan toc untuk file Penurunan harga. (Mendukung GitHub Flavoured Markdown dan Redcarpet)

2. Perbarui toc yang ada.

3. Perbarui toc otomatis saat menyimpan.

Ini tidak otomatis, tetapi menggunakan Notepad ++ ekspresi reguler:

Ganti semua pertama dengan yang kedua (menghapus semua baris yang tidak memiliki header)

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

Lalu (mengkonversi tajuk III ke spasi)

-##
        -

Lalu (mengkonversi header II ke spasi)

-#
    -

Kemudian (hapus karakter yang tidak digunakan di awal dan di akhir judul tautan)

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

Kemudian (konversikan token terakhir dengan huruf kecil dan hilangkan spasi bukan)

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

Hapus pound akhir yang tidak terpakai dan strip awal:

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

Hapus karakter yang tidak berguna di tautan:

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

Dan akhirnya tambahkan tanda kurung di sekitar tautan akhir:

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

Dan voila! Anda bahkan dapat menempatkan ini dalam makro global jika Anda mengulanginya cukup waktu.

Itu tidak mungkin, kecuali untuk solusi yang diusulkan.

Saya mengusulkan ekstensi Kramdown TOC dan kemungkinan lain untuk [email protected] dan Steven! Ragnarok menjawab dengan yang biasa:

Terima kasih atas saran dan tautannya. Saya akan menambahkannya ke daftar permintaan fitur internal kami agar tim dapat melihatnya.

Mari kita jawab pertanyaan ini sampai terjadi.

Solusi lain adalah dengan menggunakan Asciidoc bukan Markdown, yang membuat TOC . Saya sudah pindah ke pendekatan ini untuk konten saya saat ini.

Github Flavoured Markdown menggunakan RedCarpet sebagai mesin Markdown mereka. Dari repo RedCarpet :

: with_toc_data - tambahkan jangkar HTML ke setiap tajuk di HTML keluaran, untuk memungkinkan penautan ke setiap bagian.

Sepertinya Anda harus berada di level renderer untuk mengatur flag ini, yang jelas tidak mungkin di Github. Namun, pembaruan terbaru untuk Github Pages, tampaknya penahan otomatis diaktifkan untuk tajuk, membuat tajuk yang ditautkan. Tidak persis seperti yang Anda inginkan, tetapi mungkin membantu Anda membuat TOC untuk dokumen Anda sedikit lebih mudah (meskipun secara manual).

Cara yang sangat mudah untuk mencapai daftar isi untuk file mardown saat bekerja dengan Visual Studio Code adalah ekstensi Markdown-TOC .

Itu dapat menambahkan toc ke file penurunan harga yang ada dan bahkan menjaga agar toc tetap mutakhir.

Dimungkinkan untuk membuat halaman web secara otomatis dengan http://documentup.com/ dari README.mdfile. Itu tidak membuat TOC, tetapi bagi banyak orang mungkin bisa memecahkan alasan ingin membuat TOC.

Alternatif lain untuk Documentup adalah Flatdoc: http://ricostacruz.com/flatdoc/

Gitdown adalah preprocessor penurunan harga untuk Github.

Menggunakan Gitdown Anda dapat:

• Hasilkan Daftar Isi
• Temukan URL mati dan Pengidentifikasi Fragmen
• Sertakan variabel
• Sertakan file
• Dapatkan ukuran file
• Hasilkan Lencana
• Tanggal cetak
• Cetak informasi tentang repositori itu sendiri

Gitdown merampingkan tugas-tugas umum yang terkait dengan memelihara halaman dokumentasi untuk repositori GitHub.

Menggunakannya secara langsung:

var Gitdown = require('gitdown');

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

Anda dapat memilikinya sebagai skrip terpisah atau menjadikannya sebagai bagian dari rutin skrip build (seperti Gulp ).

Gunakan coryfklein / doctoc , garpu thlorenz / doctoc yang tidak menambahkan " dihasilkan dengan DocToc " ke setiap daftar isi.

npm install -g coryfklein/doctoc

Rekan saya @schmiedc dan saya telah membuat skrip GreaseMonkey yang memasang TOCtombol baru di sebelah kiri h1tombol yang menggunakan markdown-jspustaka luar biasa untuk menambah / menyegarkan daftar isi.

Keuntungan dibandingkan solusi seperti doctoc adalah bahwa ia terintegrasi ke dalam editor wiki GitHub dan tidak memerlukan pengguna untuk bekerja pada command-line mereka (dan mengharuskan pengguna untuk menginstal alat seperti node.js ). Di Chrome, ia bekerja dengan menyeret dan menjatuhkannya ke halaman Extensions, di Firefox Anda harus menginstal ekstensi GreaseMonkey.

Ini akan bekerja dengan penurunan harga biasa (yaitu tidak menangani blok kode dengan benar, karena itu adalah ekstensi GitHub ke penurunan harga). Kontribusi diterima.

Ini bukan jawaban langsung untuk pertanyaan ini karena begitu banyak orang telah memberikan solusi. Saya tidak berpikir menghasilkan TOC secara resmi didukung oleh Github hingga saat ini. Jika Anda ingin GitHub membuat Daftar Isi pada halaman pratinjau GFM mereka secara otomatis, silakan berpartisipasi dalam diskusi tentang masalah permintaan fitur resmi .

Saat ini tidak mungkin menggunakan sintaks markdown (lihat diskusi yang sedang berlangsung di GitHub ), namun Anda dapat menggunakan beberapa alat eksternal seperti:

• Generator Daftar Konten Online ( raychenon / play-table-of-content )
• arthurhammer / github-toc - ekstensi browser yang menambahkan daftar isi ke repositori GitHub

Sebagai AsciiDocgantinya gunakan (misalnya README.adoc), misalnya

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

## A

### A2

## B

### B2

seperti yang disarankan dalam komentar ini . Lihat demo di sini .

Untuk Texteditor Atom Github, periksa plugin yang luar biasa ini (atau "paket" dalam Atom-lingo), yang menghasilkan "TOC (daftar isi) dari berita utama dari parsed markdown" file:

penurunan harga-toc

Setelah diinstal sebagai paket Atom, Anda dapat menggunakan pintasan ctrl-alt-cuntuk menyisipkan TOC berdasarkan pada struktur penurunan-dokumen Anda pada posisi kursor saat ini ...

Tangkapan layar:

Pengikat Kunci Atom

markdown-toc memberi Anda binding kunci default berikut untuk mengontrol plugin di Atom:

• ctrl-alt-c => buat TOC pada posisi kursor
• ctrl-alt-u => perbarui TOC
• ctrl-alt-r => hapus TOC

Fitur Plugin (dari README proyek)

• Tautan otomatis melalui tag jangkar, mis. # A 1→#a-1
• Kontrol kedalaman [1-6] dengan depthFrom:1dandepthTo:6
• Aktifkan atau nonaktifkan tautan dengan withLinks:1
• Segarkan daftar di simpan dengan updateOnSave:1
• Gunakan daftar yang dipesan (1. ..., 2. ...) dengan orderedList:0

Inilah skrip shell yang saya lempar bersama hari ini untuk ini. Mungkin perlu mengubah untuk kebutuhan Anda, tetapi itu harus menjadi titik awal yang baik.

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/^#//'

Jika ada yang tahu cara yang lebih baik untuk melakukan penggantian # final itu, silakan tambahkan komentar. Saya mencoba berbagai hal dan tidak senang dengan apa pun, jadi saya dengan kasar memaksanya.

Sekarang ada Tindakan GitHub yang menyelesaikan ini:

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

1. Tentukan lokasi TOC (opsi) misalnya README.md

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

2. Atur alur kerja misalnya .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

Mayoritas jawaban lain perlu menginstal beberapa alat. Saya menemukan solusi online yang cepat dan mudah https://imthenachoman.github.io/nGitHubTOC .

Untuk input markdown apa pun menghasilkan tabel output konten. Anda dapat menentukan level heading minimum dan maksimum.

Kode sumbernya terletak di https://github.com/imthenachoman/nGitHubTOC