TOC otomatis dalam github-flavoured-markdown


215

Apakah mungkin membuat Daftar Isi otomatis menggunakan Github Flavoured Markdown ?


2
coba ditandai-toc , itu tidak bisa lebih mudah.
jonschlinkert

1
Jika Anda menggunakan linux dan tidak ingin menginstal perangkat lunak tambahan, coba github-markdown-toc (hanya awk di bawah tenda).
shorrty

Saya merender beberapa file penurunan harga di dalam templat jade menjadi html. Jadi saya perlu TOC saya untuk memuat lebih banyak informasi daripada yang ditemukan dalam satu file penurunan harga. Solusi saya adalah menghasilkan TOC dari kode HTML itu sendiri dengan perpustakaan node.jstoc
Plato

2
Saya telah membuat tiga generator TOC penurunan harga yang berbeda yang mencoba untuk "melakukannya dengan benar", termasuk ditandai-toc yang tercantum di atas. markdown-toc adalah favorit saya, itu menggunakan parser penurunan harga nyata ( luar biasa yang mengikuti [commonmark] (commonmark.org) spec, memungkinkan TOC diperbarui, memiliki CLI dan API, dan sekarang digunakan pada ribuan proyek
jonschlinkert

Jawaban:


141

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

Alat Baris Perintah DocToc ( sumber ) membutuhkan node.js

Instalasi:

npm install doctoc

Pemakaian:

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 .


3
TOC terlihat bagus, tetapi GitHub tidak menghasilkan jangkar untuk bagian yang sebenarnya, jadi tautannya putus. Saya akan menambahkannya secara manual untuk saat ini. Ini adalah wiki GitHub.
Matthew Flaschen

2
Ini dicatat sebagai masalah GitHub, jangkar otomatis untuk judul di wiki .
Matthew Flaschen

1
Jika Anda merasa ini sama menjengkelkannya dengan saya, buka tautan di komentar @ MatthewFlaschen dan beri +1 pada masalah ini.
blak3r

2
@MatthewFlaschen Tautan Anda rusak - alamat baru adalah github.com/gollum/gollum/issues/380
Adam Spires

3
aplikasi web DocToc tidak berfungsi. Saya menggunakan markdown-toc
DynamicDan

23

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.


1
Ini tidak berfungsi. Itu membuat teks itu. Bisakah Anda menautkan file yang menggunakan TOC seperti itu?
Geoffrey De Smet


2
Perhatikan bahwa ini adalah fitur Maruku, bukan Markdown per se, dan mungkin bahkan bukan GH Flavoured Markdown. GH-halaman memang menggunakan Maruku.
Rebecca Scott

@KevinSuttle Anda yakin? Jekyll termasuk redcarpet tetapi maruku masih terlihat seperti default (kecuali GH menggunakan konfigurasi jekyll yang
Rebecca Scott

10
@BenScott Sepertinya solusi Anda hanya berfungsi untuk halaman github. Apakah Anda tahu solusi untuk github wiki?
Pemrogram ulang

13

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:

vim-markdown-toc

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.


pastikan untuk menemukan gaya TOC umum jika Anda berkolaborasi pada file .md dan editor / plugin yang berbeda terlibat untuk tidak mendapatkan perubahan pada TOC di setiap komit lainnya. Kemungkinan penambahan ~/.vimrcuntuk ini: ubah daftar karakter dengan let g:vmt_list_item_char = "-", sertakan tajuk sebelum TOC dengan let g:vmt_include_headings_before = 1. Lihat bagian opsi dokumen untuk lebih, misalnya bagaimana mengubah teks pagar.
Wolfson

9

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.


9

Itu tidak mungkin, kecuali untuk solusi yang diusulkan.

Saya mengusulkan ekstensi Kramdown TOC dan kemungkinan lain untuk support@github.com 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.


Saya lebih suka berharap GFM menyediakannya suatu hari nanti. Ini benar-benar hal yang sopan bagi saya sementara Markdown SourceForge memiliki sintaks untuk menghasilkan TOC ini secara default.
Chetabahana

8

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).


5

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.

masukkan deskripsi gambar di sini


Pengaya kode VS yang bagus (dukungan .md yang bagus dengan fitur-fitur bagus termasuk GitHub & GitLab flavoured TOC) adalah markdown-all-in-one .
Wolfson


3

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 ).



1

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.


Terimakasih banyak! Saya harus menggunakan Tampermonkey seperti yang disarankan oleh jawaban ini untuk menginstalnya di Chrome, dan itu berhasil! Apa yang diperlukan untuk membuat skrip Anda menghasilkan TOC untuk file penurunan harga normal di repo github?
lifebalance

1

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 .


0

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


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 .


Hosting Generator Table Of Content Online (raychenon / play-table-of-content) di tableofcontent.eu "berhenti karena biaya AWS.
Michael Freidgeim

0

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:

masukkan deskripsi gambar di sini

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

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.


0

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 -->
  1. 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

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.