Automatyczny spis treści w github-flavored-markdown

Czy można wygenerować automatyczny spis treści za pomocą Github Flavored Markdown ?

Stworzyłem dwie opcje generowania toc dla github-flavored-markdown:

Narzędzie wiersza polecenia DocToc ( źródło ) wymaga node.js

npm install doctoc

npx doctoc . aby dodać spis treści do wszystkich plików przecen w bieżącym i we wszystkich podkatalogach.

DocToc WebApp

Jeśli chcesz najpierw wypróbować online, przejdź do strony doctoc , wklej link na stronie Markdown , a wygeneruje spis treści, który możesz wstawić u góry pliku Markdown.

Wiki i kotwice Github

Jak zauważył Matthew Flaschen w komentarzach poniżej, na swoich stronach wiki GitHub wcześniej nie generował kotwic, które doctoczależą.

AKTUALIZACJA: Naprawili jednak ten problem .

Strony GitHub (które są zasadniczo opakowaniem dla Jekylla) wydają się używać kramdown , który implementuje wszystkie Maruku , a zatem ma obsługę automatycznie generowanego spisu treści za pomocą tocatrybutu:

* auto-gen TOC:
{:toc}

Pierwszy wiersz po prostu rozpoczyna nieuporządkowaną listę i jest faktycznie wyrzucany.

Powoduje to zagnieżdżenie zestawu nieuporządkowanych list przy użyciu nagłówków w dokumencie.

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

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

Użycie jest proste, wystarczy przesunąć kursor w miejsce, w którym chcesz dołączyć spis treści i uruchomić :GenTocGFM, gotowe!

Zrzuty ekranu:

Cechy:

1. Wygeneruj toc dla plików Markdown. (Wsparcie GitHub Flavored Markdown i Redcarpet)

2. Zaktualizuj istniejące toc.

3. Automatyczna aktualizacja do zapisania.

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

Zamień wszystkie pierwsze na drugie (usuwa wszystkie wiersze bez nagłówków)

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

Następnie (konwertuje nagłówki III na spacje)

-##
        -

Następnie (konwertuje nagłówki II na spacje)

-#
    -

Następnie (usuń nieużywane znaki na początku i na końcu tytułu linku)

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

Następnie (zamień ostatnie tokeny małymi i myślnikami zamiast spacji)

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

Usuń nieużywane końcowe funty i początkowe myślniki:

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

Usuń niepotrzebne znaki w linkach:

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

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

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

I voila! Możesz nawet umieścić to w makro globalnym, jeśli powtórzysz to wystarczająco długo.

Nie jest to możliwe, z wyjątkiem proponowanych obejść.

I zaproponował rozszerzenie Kramdown TOC i inne możliwości support@github.com i Steven! Ragnarök odpowiedział zwykłym:

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

Głosujmy za tym pytaniem, aż to się stanie.

Innym obejściem jest użycie Asciidoc zamiast Markdown, który renderuje spis treści . Przeszedłem do tego podejścia do moich treści w dzisiejszych czasach.

Github Flavored Markdown używa RedCarpet jako silnika Markdown. Z repozytorium RedCarpet :

: with_toc_data - dodaj zakotwiczenia HTML do każdego nagłówka wyjściowego HTML, aby umożliwić połączenie z każdą sekcją.

Wygląda na to, że trzeba ustawić poziom renderera, aby ustawić tę flagę, co oczywiście nie jest możliwe w Github. Jednak najnowsza aktualizacja stron Github wydaje się, że automatyczne nagłówki są włączone dla nagłówków, tworząc nagłówki możliwe do połączenia. Nie do końca to, czego chcesz, ale może ci to ułatwić tworzenie spisu treści dla twojego dokumentu (choć ręcznie).

Bardzo wygodnym sposobem na uzyskanie spisu treści dla pliku mardown podczas pracy z Visual Studio Code jest rozszerzenie Markdown-TOC .

Może dodawać toc do istniejących plików przecen, a nawet aktualizować toc przy zapisywaniu.

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

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

Gitdown jest preprocesorem obniżania cen dla Github.

Korzystając z Gitdown możesz:

• Wygeneruj spis treści
• Znajdź martwe adresy URL i identyfikatory fragmentów
• Uwzględnij zmienne
• Dołącz pliki
• Uzyskaj rozmiar pliku
• Generuj odznaki
• Data wydruku
• Wydrukuj informacje o samym repozytorium

Gitdown usprawnia typowe zadania związane z utrzymywaniem strony dokumentacji dla repozytorium GitHub.

Korzystanie z niego jest proste:

var Gitdown = require('gitdown');

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

Możesz mieć go jako osobny skrypt lub jako część procedury skryptu kompilacji (na przykład Gulp ).

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

npm install -g coryfklein/doctoc

Mój kolega @schmiedc i ja stworzyliśmy skrypt GreaseMonkey, który instaluje nowy TOCprzycisk po lewej stronie h1przycisku, który używa doskonałej markdown-jsbiblioteki do dodawania / odświeżania spisu treści.

Przewagą nad rozwiązaniami takimi jak doctoc jest to, że integruje się z edytorem wiki GitHub i nie wymaga od użytkowników pracy przy użyciu wiersza poleceń (i wymaga od użytkowników instalowania narzędzi takich jak node.js ). W Chrome działa poprzez przeciągnięcie i upuszczenie na stronie Rozszerzenia, w przeglądarce Firefox musisz zainstalować rozszerzenie GreaseMonkey.

Będzie działał z prostym markdown (tzn. Nie będzie poprawnie obsługiwał bloków kodu, ponieważ jest to rozszerzenie GitHub do markdown). Wkłady mile widziane.

To nie jest bezpośrednia odpowiedź na to pytanie, ponieważ tak wiele osób zapewniło obejścia. Nie sądzę, aby generowanie spisu treści było dotychczas oficjalnie wspierane przez Github. Jeśli chcesz, aby GitHub automatycznie renderował spis treści na swoich stronach podglądu GFM, weź udział w dyskusji na temat oficjalnego żądania funkcji .

Obecnie nie jest możliwe użycie składni Markdown (patrz bieżąca dyskusja na GitHub ), jednak możesz użyć niektórych narzędzi zewnętrznych, takich jak:

• 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

Alternatywnie użyj AsciiDoczamiast tego (np. README.adoc), Np

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

## A

### A2

## B

### B2

zgodnie z sugestią w tym komentarzu . Sprawdź wersję demo tutaj .

W przypadku Texteditor Atom Githuba sprawdź tę niesamowitą wtyczkę (lub „pakiet” w Atom-lingo), która generuje „TOC (spis treści) nagłówków z przeanalizowanych plików przecen” :

markdown-toc

Po zainstalowaniu jako pakiet Atom możesz użyć skrótu, ctrl-alt-caby wstawić spis treści w oparciu o strukturę docdown-doc w bieżącej pozycji kursora ...

Zrzuty ekranu:

Wiązania klawiszy Atom

markdown-toc daje następujące domyślne powiązania klawiszy do kontrolowania wtyczki w Atom:

• ctrl-alt-c => utwórz spis treści w pozycji kursora
• ctrl-alt-u => aktualizacja spisu treści
• ctrl-alt-r => usuń spis treści

Funkcje wtyczek (z README projektu)

• Automatyczne łączenie za pomocą znaczników kotwicy, np. # A 1→#a-1
• Kontrola głębokości [1-6] za pomocą depthFrom:1idepthTo:6
• Włącz lub wyłącz linki za pomocą withLinks:1
• Odśwież listę po zapisaniu za pomocą updateOnSave:1
• Użyj listy uporządkowanej (1. ..., 2. ...) za pomocą orderedList:0

Oto skrypt powłoki, który dzisiaj do tego przygotowałem. Może trzeba go dostosować do własnych potrzeb, ale powinien to być dobry punkt wyjścia.

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

Jeśli ktoś zna lepszy sposób na wykonanie tych # ostatnich wymian, dodaj komentarz. Próbowałem różnych rzeczy i nie byłem z nich zadowolony, więc brutalnie to wymusiłem.

Teraz dostępna jest akcja GitHub:

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

1. Podaj lokalizację spisu treści (opcja) np README.md

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

2. Konfiguracja pracy, np .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

Większość innych odpowiedzi wymaga zainstalowania jakiegoś narzędzia. Znalazłem szybkie i łatwe rozwiązanie online https://imthenachoman.github.io/nGitHubTOC .

Dla każdego wejścia obniżki generuje tabelę treści wyjściowych. Możesz określić minimalny i maksymalny poziom nagłówka.

Kod źródłowy znajduje się na https://github.com/imthenachoman/nGitHubTOC