Bagaimana cara membuat semacam daftar isi di wiki GitHub?

105

Jika Anda melihat di sini: http://en.wikipedia.org/wiki/Stack_Overflow

Anda akan melihat ada sedikit bagian "Konten", jika Anda mengklik salah satu tautan, itu akan mengarahkan Anda ke bagian tertentu pada halaman.

Bagaimana saya melakukan ini di GitHub wiki? Dengan penurunan harga atau apa pun yang mereka gunakan?

Evan
sumber
3
Terkait, tetapi bukan duplikat persis, yang menjelaskan lebih detail: stackoverflow.com/q/9721944/2291
Jon Adams

Jawaban:

113

Ini dengan baik ditunjukkan dalam Daftar Isi dari Cheatsheet Penurunan Harga .

##### Table of Contents  
[Headers](#headers)  
[Emphasis](#emphasis)  
...snip...    
<a name="headers"/>
## Headers

Jika Anda mengarahkan kursor ke Header di file Penurunan Harga GitHub, Anda akan melihat tautan kecil di sebelah kiri, Anda juga dapat menggunakan tautan itu. Format tautan itu adalah <project URL#<header name>. Semua <header name>harus huruf kecil.

RyPeck
sumber
36
Tentunya ada cara untuk membuatnya secara otomatis seperti MediaWiki _ _ TOC _ _?
LB--
17
@ LB--: Jika Anda mengedit halaman wiki GitHub dan mengubah menu tarik-turun "gaya pengeditan" menjadi "MediaWiki", Anda dapat langsung menggunakan MediaWiki __TOC__. Jelas ada logika pembuatan otomatis yang mendasarinya. Tetapi fungsinya tampaknya tidak diekspos dalam gaya pengeditan penurunan harga mereka. Sangat disayangkan. Mari kita semua mulai mengirimkan permintaan fitur untuk itu dan mungkin mereka akan mengaktifkannya.
Andrew Janke
3
Saya mengingkari keberadaan "logika autogenerasi yang mendasari"; sepertinya "gaya pengeditan" yang berbeda melewati penyaji yang berbeda. Tetap saja, akan sangat bagus untuk memiliki ini dalam versi MD karena itu cukup populer, dan tidak sulit untuk ditambahkan.
Andrew Janke
5
@AndrewJanke Saya memeriksanya lebih lanjut, tampaknya format MarkDown tidak memiliki dukungan untuk pembuatan otomatis daftar isi, dan mereka bangga karenanya.
LB--
6
Ada satu kendala dalam membuat tautan. Mereka harus menggunakan huruf kecil. Saya tidak tahu itu dan bertanya-tanya mengapa TOC saya tidak berfungsi. Saya digunakan #Headerssebagai pengganti #headers. Saya pikir itu salah ketik dalam jawaban Anda. Mungkin Anda dapat menambahkan informasi ini ke jawaban Anda.
t3chb0t
20

Satu solusi (semi-otomatis) yang mungkin adalah Eugene Kalinin github-markdown-toc. Alat ini pada dasarnya README.mdmengolah file Anda dan mencari #judul untuk membuat TOC.

  1. Unduh skrip https://github.com/ekalinin/github-markdown-toc
  2. Beri makan Anda README.mdke skrip (seperti yang dicatat dalam Eugene README.md)

    cat README.md | bash github-markdown-toc

  3. Potong dan tempel TOC yang dihasilkan dan letakkan di bagian atas README.mdfile Anda

Perhatikan bahwa bashimplementasi ini hanya berfungsi di Linux (dari apa yang saya tahu).

Sebagai catatan tambahan, ada implementasi golang dan mungkin lebih merepotkan untuk mulai bekerja.

John Tran
sumber
14

https://github.com/jonschlinkert/markdown-toc

  • git clone your-repo.wiki.git(tambahkan .wikihak sebelumnya .gituntuk mengkloning wiki
  • npm i -g markdown-toc
  • Sisipkan <!-- toc -->(peka huruf besar-kecil) di penurunan harga wiki Anda
  • markdown-toc -i my-wiki-markdown.md( -iakan mengeditnya di tempat)
  • Keuntungan

Pembaruan: Saya pikir mungkin https://github.com/thlorenz/doctoc lebih populer sekarang.

corysimmons
sumber
13

Saat ini tidak mungkin melakukannya menggunakan sintaks penurunan harga ( .md). Ada diskusi tidak resmi yang sedang berlangsung tentang secara otomatis membuat daftar isi TOC pada file penurunan harga yang diberikan seperti README.mdyang mencantumkan beberapa ide.

Namun ada beberapa solusi lain seperti:

kenorb
sumber
1
Ya, saya telah dikonversi ke asciidoc sebagian besar untuk ToC dan menautkan ke header. Bosan menunggu penurunan harga untuk mengejar ketinggalan.
Ciro Santilli 郝海东 冠状 病 六四 事件 法轮功
8

Jika Anda tidak dalam posisi untuk tetap dengan penurunan harga , Anda dapat melakukan seperti di bawah ini:

  • di GitHub / wiki : alihkan Penurunan harga ke MediaWiki . Gunakan __TOC__Sintaks. Lihat contoh .
  • di GitHub / repo : alihkan Markdown ke AsciiDoc . Gunakan :toc:Sintaks. Lihat demo .

Namun, dengan menggunakan file Markdown di GitHub / repo , Anda bisa mendapatkannya di Halaman GitHub seperti di Wikipedia

  • ketika Jekyll diaktifkan, itu menghasilkan Halaman GitHub menggunakan Kramdown secara default
  • Kramdown datang dengan Table Of Content. Gunakan {:toc}Sintaks. Simak penjelasannya .
Chetabahana
sumber
5

Kode Visual Studio

Jika Anda kebetulan menggunakan Visual Studio Code , ada ekstensi yang mudah digunakan yang disebut Markdown All in One yang dapat membuat TOC untuk file .md apa pun dalam sekejap.

masukkan deskripsi gambar di sini

Cukup buka Command Palette ( Ctrl-Shift-P) ->Markdown: Create Table of Contents

Md asli Setelah penyisipan TOC otomatis

Pembaruan otomatis mengacaukan Daftar Isi yang Anda edit?

Sebagai tip tambahan, Anda mungkin ingin MENONAKTIFKAN "pembaruan TOC otomatis saat menyimpan" dengan menggunakan

  "markdown.extension.toc.updateOnSave": false,

di Visual Studio Settings (Command Palette -> Preferences: Open Settings (JSON)).

np8
sumber
2

Karena fakta bahwa github memiliki caranya sendiri untuk menghasilkan atribut id = ".." di h1, h2, h3, dll ... header dalam versi html setelah memproses Penurunan harga (misalnya Bitbucket menggunakan pola yang sedikit berbeda dari judul judul yang lambat untuk id = "slug") berguna untuk tidak menemukan kembali roda dan menggunakan pustaka yang merekayasa balik proses ini.

Saya menemukan satu perpustakaan yang cukup bagus untuk tugas ini yang disebut markdown-toc .

Bagi saya ini sepertinya solusi terbaik karena saya selalu menginstal node di mesin saya.

Hanya menjalankan npx penurunan harga-toc -i file.md .

Dan sepertinya ini adalah salah satu alat yang lebih populer untuk tugas ini - setidaknya di ekosistem node.js.

ls
cat <<EOF >> test.md | tee 
## Table of Contents

<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
EOF
ls
cat test.md
npx markdown-toc -i test.md
cat test.md

keluaran:

masukkan deskripsi gambar di sini

stopopa
sumber