Jak utworzyć spis treści w witrynie wiki GitHub?

Jeśli zajrzysz tutaj: http://en.wikipedia.org/wiki/Stack_Overflow

Zauważysz, że jest tam mała sekcja „Treść”, jeśli klikniesz jeden z linków, przeniesie Cię do określonej sekcji na stronie.

Jak to zrobić w witrynie wiki GitHub? Z Markdownem czy czymkolwiek innym?

Jest to ładnie pokazane w spisie treści ściągawki Markdown .

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

Jeśli najedziesz kursorem na nagłówek w pliku Markdown GitHub, zobaczysz mały link prosty po lewej stronie, możesz również użyć tego linku. Format tego łącza to <project URL#<header name>. Wszystkie <header name>muszą być małe.

Jednym z możliwych (półautomatycznych) rozwiązań jest rozwiązanie Eugene'a Kalinina github-markdown-toc. To narzędzie w zasadzie przeszukuje twój README.mdplik i wydobywa #nagłówki, aby utworzyć spis treści.

1. Pobierz skrypt https://github.com/ekalinin/github-markdown-toc

2. Nakarm swój README.mdscenariusz (jak odnotowano w Eugene'a README.md)

   cat README.md | bash github-markdown-toc

3. Wytnij i wklej wygenerowany spis treści i umieść go na górze README.mdpliku

Zauważ, że ta bashimplementacja działa tylko na Linuksie (z tego, co mogę powiedzieć).

Na marginesie, istnieje implementacja golang i prawdopodobnie jest więcej kłopotów z rozpoczęciem pracy.

Ponieważ github nie może używać TOCbezpośrednio, ale mamy inne alternatywy.

Możesz automatycznie wygenerować spis treści za pomocą narzędzia online:

Wygeneruj spis treści z GitHub Markdown lub Wiki Online

lub za pomocą narzędzia lokalnego:

github-markdown-toc

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

• git clone your-repo.wiki.git(dodaj .wikiprawo przed, .gitaby sklonować wiki
• npm i -g markdown-toc
• Wstaw <!-- toc -->(z uwzględnieniem wielkości liter) w markdown swojej wiki
• markdown-toc -i my-wiki-markdown.md( -ibędzie edytować to na miejscu)
• Zysk

Aktualizacja: myślę, że może https://github.com/thlorenz/doctoc jest teraz bardziej popularne.

Obecnie nie jest to możliwe przy użyciu składni markdown ( .md). Trwa nieoficjalna dyskusja na temat automatycznego generowania spisu treści spisu treści na renderowanych plikach markdown, takich jak README.mdlista niektórych pomysłów.

Istnieją jednak inne obejścia, takie jak:

• Użyj AsciiDoczamiast tego zgodnie z sugestią zawartą w tym komentarzu . Na przykład:

  :toc: macro
  :toc-title:
  :toclevels: 99
  # Title
  
  toc::[]
  
  ## A
  
  ### A2
  
  ## B
  
  ### B2
  

  Sprawdź przykład w littlebits/react-popover( README.adoc) .

• Generator spisu treści online ( raychenon / play-table-of-content )

• arthurhammer / github-toc - rozszerzenie przeglądarki, które dodaje spis treści do repozytoriów GitHub

Jeśli nie jesteś w stanie trzymać się Markdown , możesz zrobić, co poniżej:

• na GitHub / wiki : przełącz Markdown na MediaWiki . Użyj __TOC__składni. Zobacz przykład .
• na GitHub / repo : przełącz Markdown na AsciiDoc . Użyj :toc:składni. Zobacz demo .

Jednak korzystając z plików Markdown w GitHub / repo , możesz je pobrać na GitHub Pages, tak jak w Wikipedii

• gdy Jekyll jest aktywowany, domyślnie generuje strony GitHub przy użyciu Kramdown
• Kramdown wyposażony Table Of Content. Użyj {:toc}składni. Zobacz wyjaśnienie .

Visual Studio Code

Jeśli zdarzy ci się używać Visual Studio Code , istnieje łatwe w użyciu rozszerzenie o nazwie Markdown All in One, które może błyskawicznie utworzyć spis treści dla dowolnego pliku .md.

Wystarczy otworzyć Command Palette ( Ctrl-Shift-P) ->Markdown: Create Table of Contents

Automatyczna aktualizacja psuje edytowany spis treści?

Dodatkową wskazówką może być WYŁĄCZENIE „automatycznej aktualizacji spisu treści przy zapisywaniu” za pomocą

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

w ustawieniach programu Visual Studio (Paleta poleceń -> Preferencje: Otwórz ustawienia (JSON)).

Możesz wybrać tryb edycji "MediaWiki", który wygeneruje toc dla nagłówków, np

== First ==

== Second ==

Ze względu na to, że github ma swój własny sposób generowania atrybutów id = ".." w nagłówkach h1, h2, h3, itd ... w wersji html po przetworzeniu Markdown (na przykład Bitbucket używa trochę innego schematu spowalniania nagłówków tytułów do id = "slug") jest wygodne, aby nie wymyślać na nowo koła i nie używać biblioteki, która dokonała inżynierii wstecznej tego procesu.

Znalazłem jedną całkiem dobrą bibliotekę do tego zadania o nazwie markdown-toc .

Wydaje mi się, że jest to najlepsze rozwiązanie, ponieważ zawsze instalowałem node'a na moim komputerze.

Wystarczy wykonać NPX Przecena-toc -i file.md .

I wygląda na to, że jest to jedno z bardziej popularnych narzędzi do tego zadania - przynajmniej w ekosystemie 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

wynik: