Automatisches Inhaltsverzeichnis in Github-Geschmacksabschlag

Ist es möglich, mit Github Flavored Markdown ein automatisches Inhaltsverzeichnis zu erstellen ?

Ich habe zwei Optionen erstellt, um ein Toc für Markdown mit Github-Geschmack zu generieren:

DocToc Command Line Tool ( Quelle ) erfordert node.js

npm install doctoc

npx doctoc . Hinzufügen eines Inhaltsverzeichnisses zu allen Markdown-Dateien im aktuellen und allen Unterverzeichnissen.

DocToc WebApp

Wenn Sie es zuerst online ausprobieren möchten, gehen Sie zur Doctoc- Site, fügen Sie den Link der Markdown-Seite ein und es wird ein Inhaltsverzeichnis generiert, das Sie oben in Ihre Markdown-Datei einfügen können.

Github Wikis und Anker

Wie Matthew Flaschen in den Kommentaren unten hervorhob, hat GitHub für seine Wiki-Seiten zuvor nicht die Anker generiert, die davon doctocabhängen.

UPDATE: Sie haben dieses Problem jedoch behoben .

GitHub Pages (im Grunde genommen ein Wrapper für Jekyll) scheint kramdown zu verwenden , das Maruku vollständig implementiert , und unterstützt daher ein automatisch generiertes Inhaltsverzeichnis über ein tocAttribut:

* auto-gen TOC:
{:toc}

Die erste Zeile startet nur eine ungeordnete Liste und wird tatsächlich weggeworfen.

Dies führt zu einem verschachtelten Satz ungeordneter Listen unter Verwendung der Überschriften im Dokument.

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 dafür gibt es keine Lösung.

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

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

Screenshots:

Eigenschaften:

1. Generieren Sie toc für Markdown-Dateien. (Unterstützt GitHub Flavored Markdown und Redcarpet)

2. Aktualisieren Sie das vorhandene toc.

3. Auto Update toc beim Speichern.

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

Ersetzen Sie alle zuerst durch die zweiten (entfernt alle Zeilen ohne Überschriften)

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

Dann (konvertiert Header III in Leerzeichen)

-##
        -

Dann (konvertiert Header II in Leerzeichen)

-#
    -

Dann (entfernen Sie nicht verwendete Zeichen am Anfang und am Ende des Link-Titels)

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

Dann (letzte Token in Kleinbuchstaben umwandeln und anstelle von Leerzeichen streichen)

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

Entfernen Sie nicht verwendete letzte Pfund und anfängliche Striche:

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

Entfernen Sie nutzlose Zeichen in Links:

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

Und schließlich fügen Sie Klammern um die letzten Links hinzu:

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

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

Es ist nicht möglich, außer für die vorgeschlagenen Problemumgehungen.

Ich schlug [email protected] und Steven die Erweiterung des TOC von Kramdown und andere Möglichkeiten vor ! Ragnarök antwortete mit dem Üblichen:

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

Lassen Sie uns diese Frage positiv bewerten, bis es passiert.

Eine andere Problemumgehung besteht darin, Asciidoc anstelle von Markdown zu verwenden, wodurch Inhaltsverzeichnisse gerendert werden . Ich bin heutzutage für meinen Inhalt zu diesem Ansatz übergegangen.

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

: with_toc_data - Fügen Sie jedem Header im Ausgabe-HTML HTML-Anker hinzu, um die Verknüpfung mit jedem Abschnitt zu ermöglichen.

Es scheint, dass Sie auf Renderer-Ebene gehen müssen, um dieses Flag zu setzen, was auf Github offensichtlich nicht möglich ist. Beim neuesten Update von Github Pages scheint die automatische Verankerung für Header aktiviert zu sein, wodurch verknüpfbare Überschriften erstellt werden. Nicht genau das, was Sie wollen, aber es könnte Ihnen helfen, ein Inhaltsverzeichnis für Ihr Dokument etwas einfacher zu erstellen (wenn auch manuell).

Eine sehr bequeme Möglichkeit, ein Inhaltsverzeichnis für eine Mardown-Datei zu erstellen, wenn Sie mit Visual Studio Code arbeiten, ist die Erweiterung Markdown-TOC .

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

Es ist möglich, automatisch eine Webseite mit http://documentup.com/ aus der README.mdDatei zu generieren . Es wird kein Inhaltsverzeichnis erstellt, aber für viele könnte es den Grund für die Erstellung eines Inhaltsverzeichnisses lösen.

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

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

Mit Gitdown können Sie:

• Inhaltsverzeichnis erstellen
• Finden Sie tote URLs und Fragment-IDs
• Variablen einschließen
• Dateien einschließen
• Dateigröße abrufen
• Abzeichen generieren
• Datum des Drucks
• Drucken Sie Informationen zum Repository selbst

Gitdown optimiert allgemeine Aufgaben im Zusammenhang mit der Verwaltung einer Dokumentationsseite für ein GitHub-Repository.

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 (z. B. Gulp ) verwenden.

Verwenden Sie coryfklein / doctoc , eine Abzweigung von thlorenz / doctoc , die nicht jedem Inhaltsverzeichnis " mit DocToc generiert " hinzufügt .

npm install -g coryfklein/doctoc

Mein Kollege @schmiedc und ich haben ein GreaseMonkey-Skript erstellt , das eine neue TOCSchaltfläche links von der h1Schaltfläche installiert, die die hervorragende markdown-jsBibliothek zum Hinzufügen / Aktualisieren eines Inhaltsverzeichnisses verwendet.

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

Es funktioniert mit einfachem Markdown (dh es werden Codeblöcke nicht korrekt behandelt, da dies eine GitHub-Erweiterung für Markdown ist). Beiträge willkommen.

Dies ist keine direkte Antwort auf diese Frage, da so viele Leute Problemumgehungen bereitgestellt haben. Ich glaube nicht, dass die Erstellung eines Inhaltsverzeichnisses bisher offiziell von Github unterstützt wurde. Wenn Sie möchten, dass GitHub automatisch ein Inhaltsverzeichnis auf den GFM-Vorschauseiten rendert, nehmen Sie an der Diskussion zum offiziellen Problem mit Funktionsanfragen teil .

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

• Online- Inhaltsverzeichnis-Generator ( Raychenon / Play-Inhaltsverzeichnis )
• arthurhammer / github-toc - Browsererweiterung, die GitHub-Repos ein Inhaltsverzeichnis hinzufügt

Alternativ können Sie AsciiDocstattdessen (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 .

Für Githubs Texteditor Atom sehen Sie sich dieses fantastische Plugin (oder "Paket" in Atom-lingo) an, das "Inhaltsverzeichnis) von Überschriften aus analysierten Markdown- Dateien generiert :

Markdown-toc

Einmal als Atom-Paket installiert, können Sie über die Verknüpfung ctrl-alt-cein Inhaltsverzeichnis basierend auf Ihrer Markdown-Doc-Struktur an der aktuellen Cursorposition einfügen ...

Screenshots:

Atom-Tastenkombinationen

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. B. # A 1→#a-1
• Tiefenkontrolle [1-6] mit depthFrom:1 unddepthTo:6
• Aktivieren oder deaktivieren Sie Links mit withLinks:1
• Liste beim Speichern mit aktualisieren updateOnSave:1
• Verwenden Sie die geordnete Liste (1. ..., 2. ...) mit orderedList:0

Hier ist ein Shell-Skript, das ich heute dafür zusammengestellt habe. Möglicherweise müssen Sie es an Ihre Bedürfnisse anpassen, 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.

Es gibt jetzt eine GitHub-Aktion, die dies erreicht:

https://github.com/marketplace/actions/toc-generator

1. Geben Sie den Ort des Inhaltsverzeichnisses an (Option), z README.md

<!-- START doctoc -->
<!-- END doctoc -->

2. Workflow einrichten z .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

Die meisten anderen Antworten erfordern die Installation eines Tools. Ich habe eine schnelle und einfache Online-Lösung gefunden: https://imthenachoman.github.io/nGitHubTOC .

Für jede Markdown-Eingabe wird ein Inhaltsverzeichnis generiert. Sie können die minimale und maximale Überschriftenebene angeben.

Der Quellcode befindet sich unter https://github.com/imthenachoman/nGitHubTOC