Автоматический TOC в github-flavored-markdown

Можно ли сгенерировать автоматическое оглавление, используя Github Flavored Markdown ?

Я создал две опции для генерации ток-кода для github-flavored-markdown:

Инструмент командной строки DocToc ( источник ) требует node.js

npm install doctoc

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

DocToc WebApp

Если вы хотите сначала попробовать его в Интернете, перейдите на сайт doctoc , вставьте ссылку на страницу уценки, и она сгенерирует таблицу содержимого, которую вы можете вставить вверху файла уценки.

Github Wikis и якоря

Как отметил Мэтью Флашен в комментариях ниже, для своих вики-страниц GitHub ранее не генерировал якорей, doctocот которых зависит.

ОБНОВЛЕНИЕ: Тем не менее, они исправили эту проблему .

GitHub Pages (который по сути является оберткой для Jekyll), похоже, использует kramdown , который реализует весь Maruku и, следовательно, имеет поддержку автоматически сгенерированного оглавления через tocатрибут:

* auto-gen TOC:
{:toc}

Первая строка только начинает неупорядоченный список и фактически выбрасывается.

Это приводит к вложенному набору неупорядоченных списков с использованием заголовков в документе.

Примечание: это должно работать для страниц GitHub, а не для GitHub Flavored Markdown (GFM), используемого в комментариях или вики-страницах. AFAIK решение для этого не существует.

Если вы редактируете файлы Markdown с помощью Vim, вы можете попробовать этот плагин vim-markdown-toc .

Использование простое, просто наведите курсор на то место, куда вы хотите добавить оглавление, и бегите :GenTocGFM, готово!

Скриншоты:

Особенности:

1. Генерация ток для файлов Markdown. (Поддержка GitHub со вкусом уценки и Redcarpet)

2. Обновите существующий ток.

3. Автоматическое обновление ток при сохранении.

Он не автоматический, но использует регулярные выражения Notepad ++:

Заменить все первое на второе (удаляет все строки, не имеющие заголовков)

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

Затем (преобразует заголовки III в пробелы)

-##
        -

Затем (преобразует заголовки II в пробелы)

-#
    -

Затем (удалите неиспользованные символы в начале и в конце заголовка ссылки)

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

Затем (преобразовать последние токены в нижний регистр и тире вместо пробелов)

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

Удалите неиспользованные последние фунты и начальные тире:

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

Удалите ненужные символы в ссылках:

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

И, наконец, добавьте круглые скобки вокруг заключительных ссылок:

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

И вуаля! Вы даже можете поместить это в глобальный макрос, если будете повторять это достаточно времени.

Это невозможно, за исключением предложенных обходных путей.

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

Спасибо за предложение и ссылки. Я добавлю его в наш внутренний список запросов, чтобы команда могла его увидеть.

Давайте поднимем этот вопрос, пока он не случится.

Другой обходной путь - использовать Asciidoc вместо Markdown, который отображает оглавления . Я перешел на этот подход для моего контента в настоящее время.

Github Flavored Markdown использует RedCarpet в качестве движка Markdown. Из репо RedCarpet :

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

Похоже, вам нужно попасть на уровень рендера, чтобы установить этот флаг, что, очевидно, невозможно на Github. Тем не менее, в последнем обновлении Github Pages, похоже, что автоматическая привязка для заголовков включена, создавая связываемые заголовки. Не совсем то, что вы хотите, но это может помочь вам создать оглавление для вашего документа немного (хотя и вручную).

Очень удобным способом получения оглавления для файла разметки при работе с кодом Visual Studio является расширение 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 для разметки). Взносы приветствуются.

Это не прямой ответ на этот вопрос, так как многие люди нашли обходные пути. Я не думаю, что генерация оглавления официально поддерживается Github. Если вы хотите, чтобы GitHub автоматически отображал оглавление на своих страницах предварительного просмотра GFM, примите участие в обсуждении официального вопроса о запросе функции .

В настоящее время невозможно использовать синтаксис уценки (см. Текущее обсуждение на GitHub ), однако вы можете использовать некоторые внешние инструменты, такие как:

• Онлайновый генератор содержимого ( raychenon / play-of-content )
• arthurhammer / github-toc - расширение браузера, которое добавляет оглавление в репозитории GitHub

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

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

## A

### A2

## B

### B2

как предложено в этом комментарии . Проверьте демо здесь .

Для Github's Texteditor Atom проверьте этот удивительный плагин (или «пакет» в Atom-lingo), который генерирует «TOC (оглавление) заголовков из проанализированных файлов уценки» :

уценки-TOC

После установки в виде Atom-пакета вы можете использовать ярлык ctrl-alt-cдля вставки оглавления на основе вашей markdown-doc-структуры в текущей позиции курсора ...

Скриншоты:

Atom Keybindings

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

• ctrl-alt-c => создать оглавление в позиции курсора
• ctrl-alt-u => обновить оглавление
• ctrl-alt-r => удалить оглавление

Особенности плагина (из 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, выполняющее это:

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

1. Укажите местоположение оглавления (опция), например 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.