it-swarm.com.de

Automatischer TOC im Github-Geschmacksabschlag

Kann man mit Github Flavored Markdown ein automatisches Inhaltsverzeichnis erstellen?

195
Roberto Aloi

Ich habe zwei Optionen erstellt, um einen Toc für Github-Marked-Markdown zu generieren:

DocToc-Befehlszeilentool ( source ) erfordert node.js

npm install -g doctoc

doctoc ., um das Inhaltsverzeichnis zu allen Markdown-Dateien im aktuellen und allen Unterverzeichnissen hinzuzufügen.

DocToc WebApp

Wenn Sie es online ausprobieren möchten, gehen Sie zur Seite doctoc , Fügen Sie den Link der Markdown-Seite ein und es wird eine Tabelle mit. Inhalt, den Sie oben in Ihre Markdown-Datei einfügen können. </ strike>

Github Wikis und Anker

Wie Matthew Flaschen in den Kommentaren unten betonte, hat GitHub für seine Wiki-Seiten zuvor keine Anker generiert, von denen doctoc abhängt.

UPDATE: Sie haben jedoch dieses Problem behoben.

131
Thorsten Lorenz

GitHub Pages (im Grunde ein Wrapper für Jekyll) scheint Kramdown zu verwenden , die implementiert alle Maruku und unterstützt daher ein automatisch generiertes Inhaltsverzeichnis über ein toc-Attribut:

* auto-gen TOC:
{:toc}

Die erste Zeile beginnt nur mit einer ungeordneten Liste und wird tatsächlich weggeworfen.

Dies führt zu einer verschachtelten Menge ungeordneter Listen, die die Kopfzeilen im Dokument verwenden.

Hinweis: Dies sollte für GitHub-Seiten funktionieren, nicht für GitHub Flavored Markdown (GFM), wie es in Kommentaren oder Wiki-Seiten verwendet wird. AFAIK eine Lösung gibt es dafür nicht.

24
Ben Scott

Es ist nicht automatisch, verwendet jedoch reguläre Ausdrücke von Notepad ++:

Ersetze alle ersten durch die zweite (entfernt alle Zeilen ohne Header)

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

Dann (wandelt die Kopfzeilen III in Leerzeichen um)

-##
        -

Dann (konvertiert Header II in Leerzeichen)

-#
    -

Dann (entfernen Sie nicht verwendete Zeichen am Anfang und am Ende des Linktitels)

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

Dann (konvertiere die letzten Token in Kleinbuchstaben und Bindestriche anstelle von Leerzeichen)

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

Entfernen Sie nicht verwendete letzte Pfunde und erste Bindestriche:

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

Entferne nutzlose Zeichen in Links:

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

Fügen Sie abschließend noch Klammern um die letzten Links ein:

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

Und voilà! Sie können dies sogar in ein globales Makro einfügen, wenn Sie es genügend Zeit wiederholen.

9
Mikaël Mayer

Wenn Sie Markdown-Dateien mit Vim bearbeiten, können Sie dieses Plugin vim-markdown-toc verwenden.

Die Verwendung ist einfach. Bewegen Sie einfach den Cursor an die Stelle, an der Sie das Inhaltsverzeichnis anhängen möchten, und führen Sie :GenTocGFM aus. Fertig!

Screenshots:

vim-markdown-toc

Eigenschaften:

  1. Toc für Markdown-Dateien generieren. (Unterstützt GitHub Flavored Markdown und Redcarpet)

  2. Vorhandenen Toc aktualisieren.

  3. Automatisches Update beim Speichern.

8
Zhuang Ma

Github Flavored Markdown verwendet RedCarpet als Markdown-Engine . Aus dem RedCarpet-Repo :

: with_toc_data - fügt jedem Header im Ausgabe-HTML-Code HTML-Anker hinzu, Verknüpfung zu jedem Abschnitt zulassen.

Es scheint, als müsste man auf Renderer-Ebene gehen, um dieses Flag zu setzen, was bei Github offensichtlich nicht möglich ist. Beim latest Update zu Github Pages scheint es jedoch, dass die automatische Verankerung für Überschriften aktiviert ist, sodass verknüpfte Überschriften erstellt werden. Nicht genau das, was Sie möchten, aber es kann Ihnen helfen, ein Inhaltsverzeichnis für Ihr Dokument zu erstellen (wenn auch manuell).

7
Kevin Suttle

Es ist nicht möglich, mit Ausnahme der vorgeschlagenen Problemumgehungen.

Ich vorgeschlagen Kramdown TOC extension und andere Möglichkeiten, um [email protected] und Steven! Ragnarök antworteten mit dem üblichen:

Danke für den Vorschlag und die Links. Ich füge es unserer internen Funktionsanforderungsliste hinzu, damit das Team es sehen kann.

Lassen Sie uns diese Frage so lange auf den Punkt bringen, bis sie passiert.

Eine andere (im Allgemeinen inakzeptable) Problemumgehung ist die Verwendung von asciidoc anstelle von Markdown, das TOCs rendert .

Mit http://documentup.com/ kann aus der README.md-Datei automatisch eine Webseite erstellt werden. Es wird kein Inhaltsverzeichnis erstellt, aber für viele ist es vielleicht der Grund, warum ein Inhaltsverzeichnis erstellt werden soll.

Eine weitere Alternative zu Documentup ist Flatdoc: http://ricostacruz.com/flatdoc/

4
Nils

Ein sehr bequemer Weg, um ein Inhaltsverzeichnis für eine Mardown-Datei zu erhalten, wenn Sie mit Visual Studio Code arbeiten, ist die Erweiterung Markdown-TOC .

Es kann einen Token zu vorhandenen Markdown-Dateien hinzufügen und den Toc beim Speichern sogar auf dem neuesten Stand halten.

 enter image description here

3
Mathias Dpunkt

Gitdown ist ein Abschriften-Präprozessor für Github.

Mit Gitdown können Sie:

  • Inhaltsverzeichnis generieren
  • Finden Sie tote URLs und Fragmentkennungen
  • Variablen einschließen
  • Dateien einschließen
  • Dateigröße abrufen
  • Abzeichen erzeugen
  • Datum des Drucks
  • Informationen zum Repository selbst ausgeben

Gitdown rationalisiert allgemeine Aufgaben, die mit der Verwaltung einer Dokumentationsseite für ein GitHub-Repository verbunden sind.

Die Verwendung ist unkompliziert:

var Gitdown = require('gitdown');

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

Sie können es entweder als separates Skript oder als Teil der Build-Skript-Routine verwenden (z. B. Gulp ).

3
Gajus

Verwenden Sie coryfklein/doctoc , eine Gabelung von thlorenz/doctoc , die nicht zu jedem Inhaltsverzeichnis "mitDocToc " hinzugefügt hinzufügt.

npm install -g coryfklein/doctoc
2
Cory Klein

Mein Kollege @schmiedc und ich haben ein GreaseMonkey-Skript erstellt, das eine neue TOC-Schaltfläche links von der h1-Schaltfläche installiert, die die hervorragende markdown-js-Bibliothek verwendet, um ein Inhaltsverzeichnis hinzuzufügen/zu aktualisieren.

Der Vorteil gegenüber Lösungen wie doctoc ist, dass es in GitHub's Wiki-Editor integriert ist und keine Benutzer an der Befehlszeile arbeiten müssen (und dass Benutzer Tools wie node.js installieren müssen). In Chrome funktioniert dies durch Ziehen und Ablegen auf der Erweiterungsseite. In Firefox müssen Sie die GreaseMonkey-Erweiterung installieren.

Es funktioniert mit normalem Markdown (d. H. Es verarbeitet Codeblöcke nicht korrekt, da dies eine GitHub-Erweiterung für Markdown ist). Beiträge willkommen.

1

Derzeit ist nicht möglich mit der Markdown-Syntax (siehe die laufende Diskussion bei GitHub ). Sie können jedoch einige externe Tools verwenden, wie:


Alternativ können Sie stattdessen AsciiDoc verwenden (z. B. README.adoc), z.

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

## A

### A2

## B

### B2

wie in diesem Kommentar vorgeschlagen . Überprüfen Sie die Demo hier .

0
kenorb

Für Github's Texteditor Atom sollten Sie sich dieses fantastische Plugin (oder "Paket" in Atom-lingo) ansehen, das "Inhaltsverzeichnis (Inhaltsverzeichnis)) von Schlagzeilen aus geparsten Markdowns" -Dateien generiert : 

markdown-toc

Nach der Installation als Atom-Paket können Sie die Verknüpfung ctrl-alt-c verwenden, um ein Inhaltsverzeichnis basierend auf Ihrer Markdown-Doc-Struktur an der aktuellen Cursorposition einzufügen. 

Screenshots:

 enter image description here

Atom Keybindings

markdown-toc bietet Ihnen die folgenden Standard-Tastenkombinationen zur Steuerung des Plugins in Atom: 

  • ctrl-alt-c => Erstellen Sie das Inhaltsverzeichnis an der Cursorposition 
  • ctrl-alt-u => Inhaltsverzeichnis aktualisieren 
  • ctrl-alt-r => Inhaltsverzeichnis löschen 

Plugin-Funktionen (aus der README-Datei des Projekts)

  • Automatische Verknüpfung über Ankertags, z. # A 1#a-1
  • Tiefensteuerung [1-6] mit depthFrom:1 und depthTo:6
  • Aktivieren oder deaktivieren Sie Links mit withLinks:1
  • Liste beim Speichern mit updateOnSave:1 aktualisieren
  • Benutze die geordnete Liste (1. ..., 2. ...) mit orderedList:0
0
Mayinx

Hier ist ein Shell-Skript, das ich heute zusammengestellt habe. Möglicherweise müssen Sie es für Ihre Bedürfnisse optimieren, aber es sollte ein guter Ausgangspunkt sein.

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

Wenn jemand einen besseren Weg kennt, um diese endgültigen # Ersetzungen vorzunehmen, fügen Sie bitte einen Kommentar hinzu. Ich habe verschiedene Dinge ausprobiert und war mit keinem zufrieden, also habe ich es nur brutal erzwungen.

0
John Eikenberry

Dies ist keine direkte Antwort auf diese Frage, da so viele Leute Workarounds zur Verfügung gestellt haben. Ich glaube nicht, dass die Erstellung eines Inhaltsverzeichnisses bisher offiziell von Github unterstützt wurde. Wenn Sie möchten, dass GitHub auf seinen GFM-Vorschauseiten automatisch ein Inhaltsverzeichnis rendert, nehmen Sie an der Diskussion am offiziellen feature-Anforderungsproblem teil. 

0
Xiaodong Qi