Automatyczny TOC w GitHubie-markdown

W przeciwieństwie do innych języków, w których istnieje wiele języków, w których istnieje wiele języków, w tym Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język Angielski, Język]}

* auto-gen TOC:
{:toc}

Pierwsza linia uruchamia listę nieuporządkowaną i zostaje wyrzucona.

Powoduje to zagnieżdżenie zestawu list nieuporządkowanych, używając nagłówków w dokumencie.

Uwaga: to powinno działać dla stron GitHub, nie GitHub Flavored Markdown (GFM) jak używane w komentarzach lub stronach wiki. AFAIK rozwiązanie nie istnieje na to.

Nie jest automatyczne, ale używa wyrażeń regularnych Notepad++:

Zastąp wszystkie pierwsze przez drugie (usuwa wszystkie linie nie posiadające nagłówków)

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

Then (konwertuje nagłówki III na spacje)

-##
        -

Then (konwertuje nagłówki II na spacje)

-#
    -

Then (Usuń nieużywane znaki na początku i na końcu tytułu linku)

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

Then (Konwertuj Ostatnie tokeny małymi literami i myślnikami zamiast spacji)

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

Usuń niewykorzystane funty końcowe i początkowe myślniki:

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

Usuń bezużyteczne znaki w linkach:

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

I na koniec dodaj nawias wokół końcowych linków:

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

Jeśli edytujesz pliki Markdown za pomocą Vima, możesz wypróbować tę wtyczkę vim-markdown-toc .

Użycie jest proste, po prostu przesuń kursor w miejsce, w którym chcesz dodać spis treści i uruchom :GenTocGFM, gotowe!

Screeny:

Cechy:

1. Generowanie spisu treści dla plików Markdown. (Wsparcie GitHub, Markdown i Redcarpet)

2. Zaktualizuj istniejący spis treści.

3. Automatyczna aktualizacja toc przy zapisywaniu.

Github Flavored Markdown używa RedCarpet jako swojego silnika Markdown. Z redcarpet repo :

: with_toc_data-dodawanie anchorów HTML do każdego nagłówka w wyjściowym HTML, aby umożliwić łączenie się z każdą sekcją.

Wygląda na to, że musisz dostać się na poziomie renderera, aby ustawić tę flagę, co oczywiście nie jest możliwe na Githubie. Jednakże, ostatnia aktualizacja do stron Github, wydaje się, że automatyczne zakotwiczenie jest włączone dla nagłówków, tworząc łączone nagłówki. Nie dokładnie to, czego chcesz, ale może to pomóc w stworzeniu spisu treści dla dokumentu nieco łatwiej (choć ręcznie).

To niemożliwe, poza zaproponowanymi obejściami.

I proponuje rozszerzenie Toc i inne możliwości do [email protected] Steven! Ragnarök odpowiedział zwykle:

Dzięki za sugestię i linki. Dodam go do naszej wewnętrznej listy żądań funkcji, aby zespół mógł to zobaczyć.

Zastanówmy się nad tym pytaniem, dopóki się nie stanie.

Innym (ogólnie niedopuszczalnym) obejściem jest użycie asciidoc zamiast Markdown, , który renderuje TOCs .

Możliwe jest automatyczne wygenerowanie strony internetowej za pomocą http://documentup.com / z pliku README.md. Nie tworzy to spisu treści, ale dla wielu może to rozwiązać powód, dla którego chce się utworzyć spis treści.

Inną alternatywą dla Documentup jest Flatdoc: http://ricostacruz.com/flatdoc/

Gitdown jest preprocesorem markdown dla Github.

Używając Gitdown możesz:

• Wygeneruj spis treści
• Znajdź martwe adresy URL i identyfikatory fragmentów
• Dołącz zmienne
• Dołącz pliki
• Pobierz Rozmiar pliku
• Generuj Odznaki
• Data Wydruku
• Drukuj informacje o samym repozytorium

Gitdown usprawnia typowe zadania związane z utrzymaniem strony dokumentacji dla Repozytorium GitHub.

Używanie go jest proste:

var Gitdown = require('gitdown');

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

Możesz go mieć jako osobny skrypt lub mieć go jako część procedury budowania skryptu (np. Gulp).

Użyj coryfklein / doctoc , widelca thlorenz / doctoc , który nie dodaje " wygenerowanego z DocToc " do każdego spisu treści.

npm install -g coryfklein/doctoc

Bardzo wygodnym sposobem uzyskania spisu treści pliku mardown podczas pracy z Visual Studio Code jest rozszerzenie Markdown-Toc .

Może dodawać spis treści do istniejących plików markdown, a nawet aktualizować spis treści podczas zapisywania.

Mój kolega @schmiedc i ja stworzyliśmy skrypt GreaseMonkey , który instaluje nowy przycisk TOC na lewo od przycisku h1, który używa doskonałej biblioteki markdown-js do dodawania/odświeżania spisu treści.

Przewaga nad rozwiązaniami takimi jak doctoc polega na tym, że integruje się z edytorem Wiki Githuba i nie wymaga od użytkowników pracy nad wierszem poleceń(i wymaga od użytkowników instalacji narzędzi takich jak node.js). W Chrome działa poprzez przeciąganie i upuszczanie na stronę rozszerzeń, w Firefoksie można będzie musiał zainstalować rozszerzenie GreaseMonkey.

Będzie działać ze zwykłym znacznikiem markdown (tzn. nie obsługuje poprawnie bloków kodu, ponieważ jest to rozszerzenie GitHub do znacznika markdown). Wkład mile widziany.

Nie jest to bezpośrednia odpowiedź na to pytanie, ponieważ tak wiele osób zapewniło obejścia. Nie sądzę, aby generowanie TOC było oficjalnie wspierane przez Github jeszcze do tej pory. Jeśli chcesz, aby GitHub automatycznie renderował spis treści na swoich stronach GFM preview, weź udział w dyskusji na temat oficjalnego problemu z żądaniem funkcji .

Obecnie nie jest to Możliwe przy użyciu składni markdown (zobacz trwającą dyskusję na GitHub), jednak możesz użyć niektórych zewnętrznych narzędzi, takich jak:

• online Table Of Content Generator (raychenon / play-table-of-contents)
• [17]}arthurhammer / github-Toc - rozszerzenie przeglądarki, które dodaje spis treści do reposów GitHub

Alternatywnie użyj AsciiDoc zamiast (np. README.adoc), np.

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

## A

### A2

## B

### B2

Zgodnie z sugestią w ten komentarz . Sprawdź demo tutaj .

Dla Github 's Texteditor Atom sprawdź tę niesamowitą wtyczkę (lub" pakiet " W Atom-lingo), która generuje "TOC (spis treści) nagłówków z przetwarzanych plików markdown":

Markdown-toc

Po zainstalowaniu jako Atom-package możesz użyć skrótu ctrl-alt-c wstawianie spisu treści na podstawie struktury markdown-doc w bieżącej pozycji kursora...

Zrzuty ekranu:

Atom Keybindings

Markdown-Toc daje następujące domyślne powiązania klawiszy do sterowania Wtyczką w atomie:

• ctrl-alt-c = > Utwórz TOC w pozycji kursora
• ctrl-alt-u = > update TOC
• ctrl-alt-r = > Usuń TOC

PlugIn Features (from the project ' s README)

• automatyczne linkowanie za pomocą tagów anchor, np. # A 1 → #a-1
• regulacja głębokości [1-6] z depthFrom:1 i depthTo:6
• Włącz lub wyłącz łącza za pomocą withLinks:1
• Odśwież listę przy zapisie za pomocą updateOnSave:1
• Użyj listy uporządkowanej (1. ..., 2. ...) z orderedList:0