Wie erstelle ich eine Art Inhaltsverzeichnis im GitHub-Wiki?

100

Wenn Sie hier suchen: http://en.wikipedia.org/wiki/Stack_Overflow

Sie werden feststellen, dass es einen kleinen Abschnitt "Inhalt" gibt. Wenn Sie auf einen der Links klicken, werden Sie zu einem bestimmten Abschnitt auf der Seite weitergeleitet.

Wie mache ich das im GitHub-Wiki? Mit Markdown oder was auch immer sie verwenden?

github wiki

— Evan
quelle

3

Verwandte, aber nicht exakte Duplikate, die detaillierter behandelt werden: stackoverflow.com/q/9721944/2291

— Jon Adams

109

Dies wird im Inhaltsverzeichnis des Markdown-Cheatsheets gut demonstriert .

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

Wenn Sie den Mauszeiger über einen Header in einer GitHub Markdown-Datei bewegen, wird links davon ein kleiner Link angezeigt. Sie können diesen Link auch verwenden. Das Format für diesen Link ist <project URL#<header name>. Das <header name>muss alles in Kleinbuchstaben sein.

— RyPeck
quelle

35

Sicher gibt es eine Möglichkeit, es wie das _ _ TOC _ _ von MediaWiki automatisch zu generieren?

— LB

16

@ LB--: Wenn Sie eine GitHub-Wiki-Seite bearbeiten und das Dropdown-Menü "Bearbeitungsstil" in "MediaWiki" ändern, können Sie das MediaWiki einfach __TOC__direkt verwenden. Die zugrunde liegende Autogenerationslogik ist eindeutig vorhanden. Die Funktionalität scheint jedoch nicht in ihrem Markdown-Bearbeitungsstil verfügbar zu sein. Sehr unglücklich. Lassen Sie uns alle anfangen, Feature-Anfragen dafür zu senden, und vielleicht schalten sie es ein.

— Andrew Janke

2

Ich widerrufe die "zugrunde liegende Autogenerationslogik", die da ist; Es sieht so aus, als würden die verschiedenen "Bearbeitungsstile" verschiedene Renderer durchlaufen. Trotzdem wäre es großartig, dies in der MD-Version zu haben, da dies ziemlich beliebt ist und nicht schwer hinzuzufügen ist.

— Andrew Janke

4

@ AndrewJanke Ich habe mich genauer damit befasst. Es scheint, dass das MarkDown-Format keine Unterstützung für die automatische Generierung von Inhaltsverzeichnissen bietet, und sie sind stolz darauf.

— LB

6

Es gibt einen Haken beim Erstellen von Links. Sie müssen Kleinbuchstaben sein. Ich wusste das nicht und fragte mich, warum mein Inhaltsverzeichnis nicht funktioniert. Ich habe #Headersstatt verwendet #headers. Ich dachte, es wäre ein Tippfehler in Ihrer Antwort. Vielleicht können Sie Ihrer Antwort diese Informationen hinzufügen.

— t3chb0t

20

Eine mögliche (halbautomatische) Lösung ist die von Eugene Kalinin github-markdown-toc. Dieses Tool README.mddurchsucht im Wesentlichen Ihre Datei und entfernt die #Überschriften, um ein Inhaltsverzeichnis zu erstellen.

Laden Sie das Skript https://github.com/ekalinin/github-markdown-toc herunter
Füttere dein README.mdmit dem Skript (wie in Eugenes vermerkt README.md)

Katze README.md | Bash Github-Markdown-Toc
Schneiden Sie das generierte Inhaltsverzeichnis aus, fügen Sie es ein und platzieren Sie es oben in Ihrer README.mdDatei

Beachten Sie, dass dies bash Implementierung nur unter Linux funktioniert (soweit ich das beurteilen kann).

Als Randnotiz gibt es eine Golang- Implementierung und es ist wahrscheinlich schwieriger , sich an die Arbeit zu machen.

— John Tran
quelle

14

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

git clone your-repo.wiki.git(Fügen Sie das .wikiRecht hinzu, bevor Sie .gitdas Wiki klonen
npm i -g markdown-toc
Fügen Sie (Groß- und Kleinschreibung beachten ) in den Markdown Ihres Wikis ein
markdown-toc -i my-wiki-markdown.md( -iwird es an Ort und Stelle bearbeiten)
Profitieren

Update: Ich denke, vielleicht ist https://github.com/thlorenz/doctoc jetzt beliebter.

— Corysimmons
quelle

13

Da Github nicht TOCdirekt verwenden kann, haben wir aber andere Alternativen.

Sie können das Inhaltsverzeichnis automatisch über das Online-Tool generieren :

Generieren Sie das Inhaltsverzeichnis des Inhaltsverzeichnisses aus GitHub Markdown oder Wiki Online

oder über das lokale Tool:

github-markdown-toc

— Bravo Yeung
quelle

12

Derzeit ist dies mit der Markdown-Syntax ( ) nicht möglich.md . Es gibt eine inoffizielle Diskussion über das automatische Generieren eines Inhaltsverzeichnisses für Inhaltsverzeichnisse in gerenderten Markdown-Dateien, in README.mddenen einige der Ideen aufgelistet sind.

Es gibt jedoch einige andere Problemumgehungen wie:

Verwenden Sie AsciiDocstattdessen gemäß dem Vorschlag aus diesem Kommentar . Beispielsweise:
```
:toc: macro
:toc-title:
:toclevels: 99
# Title

toc::[]

## A

### A2

## B

### B2
```
Überprüfen Sie das Beispiel unter littlebits/react-popover( README.adoc) .
Online- Inhaltsverzeichnis-Generator ( Raychenon / Play-Inhaltsverzeichnis )
arthurhammer / github-toc - Browsererweiterung, die GitHub-Repos ein Inhaltsverzeichnis hinzufügt

— Kenorb
quelle

1

Ja, ich wurde größtenteils für den ToC und die Verknüpfung mit Headern auf asciidoc konvertiert. Ich hatte es satt, darauf zu warten, dass Markdown aufholt.

— Ciro Santilli 法轮功冠状病六四事件法轮功

8

Wenn Sie nicht in der Lage sind, bei Markdown zu bleiben , können Sie wie folgt vorgehen :

auf GitHub / Wiki : Markdown auf MediaWiki umstellen . Verwenden Sie die __TOC__Syntax. Siehe Beispiel .

auf GitHub / repo : Markdown auf AsciiDoc umschalten . Verwenden Sie die :toc:Syntax. Siehe Demo .

Verwendung jedoch Markdown - Dateien in GitHub / repo , können Sie es bekommen GitHub Seiten wie in Wikipedia

Wenn Jekyll aktiviert ist, werden standardmäßig GitHub-Seiten mit Kramdown generiert

Kramdown kommt mit Table Of Content. Verwenden Sie die {:toc}Syntax. Siehe die Erklärung .

— Chetabahana
quelle

5

Visual Studio-Code

Wenn Sie Visual Studio Code verwenden , gibt es eine benutzerfreundliche Erweiterung namens Markdown All in One , mit der das Inhaltsverzeichnis für jede MD-Datei sofort erstellt werden kann.

Öffnen Sie einfach die Befehlspalette ( Ctrl-Shift-P) ->Markdown: Create Table of Contents

Das automatische Update bringt Ihr bearbeitetes Inhaltsverzeichnis durcheinander?

Als zusätzlichen Tipp möchten Sie möglicherweise die Option "Automatische Inhaltsverzeichnisaktualisierungen beim Speichern" mit deaktivieren

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

in Ihren Visual Studio-Einstellungen (Befehlspalette -> Einstellungen: Einstellungen öffnen (JSON)).

— np8
quelle

2

Sie können den Bearbeitungsmodus "MediaWiki" wählen, der ein Token für die Header generiert, z

== First ==

== Second ==

— Stefan
quelle

Wahr. Ein Beispiel finden Sie unter github.com/bitcoin/bips/blob/master/bip-0174.mediawiki .

— Agis

2

Aufgrund der Tatsache, dass Github seine eigene Methode hat, um id = ".." - Attribute in h1, h2, h3 usw. zu generieren id = "slug") Es ist praktisch, das Rad nicht neu zu erfinden und eine Bibliothek zu verwenden, die diesen Prozess rückgängig gemacht hat.

Ich habe eine ziemlich gute Bibliothek für diese Aufgabe gefunden, Markdown-toc .

Für mich scheint es die beste Lösung zu sein, da ich immer einen Knoten auf meinem Computer installiert habe.

Führen Sie einfach npx markdown-toc -i file.md aus .

Und es sieht so aus, als wäre es eines der beliebtesten Tools für diese Aufgabe - zumindest im Ökosystem von node.j.

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

Ausgabe:

— Stoppsopa
quelle