Автоматичне TOC у відмітці з ароматом github

Чи можливо генерувати автоматичну таблицю змісту за допомогою Github Flavored Markdown ?

Я створив два варіанти для генерування току для розмітки з ароматом github:

Інструмент командного рядка DocToc ( джерело ) вимагає node.js

npm install doctoc

npx doctoc . щоб додати зміст до всіх файлів розмітки в поточному та всіх підкаталогах.

DocToc WebApp

Якщо ви хочете спробувати його в Інтернеті спочатку, перейдіть на сайт doctoc , вставте посилання сторінки розмітки , і він створить зміст, який ви можете вставити вгорі файлу розмітки.

Гітхуб Вікі і якорі

Як зазначив Меттью Флашен в коментарях нижче, для своїх вікі-сторінок GitHub раніше не створював якір, doctocвід якого залежить.

ОНОВЛЕННЯ: Однак вони вирішили цю проблему .

Сторінки GitHub (яка в основному є обгорткою для Джекілла), як видається, використовує крамдаун , який реалізує всю Maruku , і тому має підтримку автоматично створеної таблиці вмісту за допомогою tocатрибута:

* auto-gen TOC:
{:toc}

Перший рядок просто починає невпорядкований список і насправді викидається.

Це призводить до створення вкладеного набору не упорядкованих списків із використанням заголовків у документі.

Примітка. Це повинно працювати для GitHub Pages, а не GitHub Flavored Markdown (GFM), як використовується в коментарях або на сторінках вікі. AFAIK для цього не існує рішення.

Якщо ви редагуєте файли Markdown за допомогою Vim, ви можете спробувати цей плагін vim-markdown-toc .

Використання просте, просто перемістіть курсор на місце, до якого потрібно додати Зміст, та запустіть :GenTocGFM, готово!

Скріншоти:

Особливості:

1. Створення toc для файлів Markdown. (Підтримка GitHub Flavored Markdown та Redcarpet)

2. Оновіть існуючий ток.

3. Автоматичне оновлення Toc при збереженні.

Це не автоматично, але він використовує регулярні вирази Notepad ++:

Замініть все першим на друге (видаляє всі рядки без заголовків)

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

Потім (перетворює заголовки III у пробіли)

-##
        -

Потім (перетворює заголовки II у пробіли)

-#
    -

Потім (видаліть невикористані символи на початку та в кінці заголовка посилання)

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

Потім (конвертуйте останні символи в малі та тире замість пробілів)

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

Видаліть невикористані кінцеві кілограми та початкові тире:

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

Видаліть непотрібні символи у посиланнях:

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

І нарешті додайте дужки навколо кінцевих посилань:

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

І вуаля! Ви навіть можете помістити це в глобальний макрос, якщо повторите його достатньо часу.

Це неможливо, за винятком запропонованих обхідних шляхів.

Я запропонував розширення TOC Kramdown та інші можливості для support@github.com та Steven! Рагнарок відповів звичайним:

Дякуємо за пропозицію та посилання. Я додаю його до нашого внутрішнього списку запитів щодо функцій для команди.

Давайте підкреслимо це питання, поки воно не відбудеться.

Іншим способом вирішення проблеми є використання Asciidoc замість Markdown, який надає TOC . Я сьогодні перейшов до цього підходу для свого вмісту.

Github Flavored Markdown використовує RedCarpet в якості двигуна Markdown. Від репортажу RedCarpet :

: with_toc_data - додайте HTML-якорі до кожного заголовка у вихідному HTML-коді, щоб дозволити посилання на кожен розділ.

Схоже, вам потрібно буде на рівні візуалізації встановити цей прапор, що очевидно неможливо на Github. Однак, за останнім оновленням сторінок Github, схоже, що автоматичне прив’язування увімкнено для заголовків, створюючи сполучні заголовки. Не зовсім те, що ви хочете, але це може допомогти вам створити TOC для свого документа трохи простіше (хоча і вручну).

Дуже зручним способом досягнення вмісту для файлу, що перебуває у стані виходу при роботі з Visual Studio Code, є розширення Markdown-TOC .

Він може додати ток до існуючих файлів розмітки і навіть підтримувати оновлення в тоці щодо збереження.

Можна створити веб-сторінку автоматично за допомогою http://documentup.com/ з README.mdфайлу. Це не створення TOC, але для багатьох це може вирішити причину бажання створити TOC.

Ще одна альтернатива Documentup - Flatdoc: http://ricostacruz.com/flatdoc/

Gitdown - препроцесор розмітки для Github.

За допомогою Gitdown ви можете:

• Створити зміст
• Знайдіть мертві URL-адреси та ідентифікатори фрагментів
• Включити змінні
• Включити файли
• Отримати розмір файлу
• Створення значків
• Дата друку
• Роздрукуйте інформацію про сам сховище

Gitdown упорядковує поширені завдання, пов'язані із підтримкою сторінки документації для сховища GitHub.

Використовувати це просто:

var Gitdown = require('gitdown');

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

Ви можете мати його як окремий сценарій або мати його як частину звичайного сценарію побудови (наприклад, Gulp ).

Використовуйте coryfklein / doctoc , вилку thlorenz / doctoc , яка не додає " створений за допомогою DocToc " до кожної змістової таблиці.

npm install -g coryfklein/doctoc

Мій колега @schmiedc і я створили сценарій GreaseMonkey, який встановлює нову TOCкнопку зліва від h1кнопки, яка використовує відмінну markdown-jsбібліотеку для додавання / оновлення змісту.

Перевага перед такими рішеннями, як doctoc, полягає в тому, що він інтегрується у вікі-редактор GitHub і не потребує того, щоб користувачі працювали в їх командному рядку (і вимагали від користувачів встановлення таких інструментів node.js). У Chrome він працює, перетягуючи його на сторінку розширень, у Firefox вам потрібно буде встановити розширення GreaseMonkey.

Він буде працювати з простою розміткою (тобто він не обробляє кодові блоки правильно, оскільки це розширення GitHub до розмітки). Внески

Це не є прямою відповіддю на це питання, оскільки так багато людей забезпечили обхідні шляхи. Я не думаю, що генерація TOC до цього часу офіційно не підтримується Github. Якщо ви хочете, щоб GitHub автоматично надавав зміст на своїх сторінках попереднього перегляду GFM, будь ласка, прийміть участь в обговоренні питання щодо офіційного запиту на функції .

Наразі неможливо використовувати синтаксис розмітки (див. Триваючу дискусію на GitHub ), проте ви можете використовувати деякі зовнішні інструменти, такі як:

• Інтернет- генератор вмісту вмісту ( raychenon / play-table-of-content )
• arthurhammer / github-toc - розширення для браузера, яке додає зміст до репозиторії GitHub

Альтернативно використовувати AsciiDocзамість цього (наприклад README.adoc), наприклад

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

## A

### A2

## B

### B2

як запропоновано в цьому коментарі . Перевірте демонстрацію тут .

Для Texthitor Atom Github ознайомтеся з цим дивовижним плагіном (або "пакунком" в Atom-lingo), який генерує "TOC (зміст) заголовків з розбору файлів розмітки" :

відмітка-toc

Після установки Atom-пакету ви можете скористатися ярликом ctrl-alt-cдля вставки TOC на основі вашої markdown-doc-структури в поточній позиції курсору ...

Скріншоти:

Атомні клавіатури

markdown-toc надає наступні прив'язки ключів за замовчуванням для управління плагіном в Atom:

• ctrl-alt-c => створити TOC у позиції курсору
• ctrl-alt-u => оновити TOC
• ctrl-alt-r => видалити TOC

Особливості плагіна (з проекту README)

• Автоматичне посилання через теги прив’язки, наприклад # A 1→#a-1
• Контроль глибини [1-6] з depthFrom:1таdepthTo:6
• Увімкнути або вимкнути посилання за допомогою withLinks:1
• Оновити список для збереження за допомогою updateOnSave:1
• Використовуйте упорядкований список (1. ..., 2. ...) з orderedList:0

Ось скрипт оболонки, який я сьогодні для цього зібрав разом. Можливо, потрібно підправити це для ваших потреб, але це повинно бути гарним відправною точкою.

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

Якщо хтось знає кращий спосіб зробити ці остаточні # заміни, будь ласка, додайте коментар. Я пробував різні речі і не був задоволений жодною, тому я просто змусив це.

Зараз GitHub Action виконує це:

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

1. Вкажіть місце TOC (опція), наприклад README.md

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

2. Налаштування робочого процесу, наприклад .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

Більшість інших відповідей вимагають встановити якийсь інструмент. Я знайшов швидке та просте онлайн-рішення https://imthenachoman.github.io/nGitHubTOC .

Для будь-якого введення розмітки він створює таблицю виведення вмісту. Ви можете вказати мінімальний та максимальний рівень заголовка.

Вихідний код знаходиться за адресою https://github.com/imthenachoman/nGitHubTOC