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

Question

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

Answer 1

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

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

Установка:

npm install -g doctoc

Использование:

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

DocToc WebApp

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

Github Wikis and Anchors

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

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

Answer 2

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

* auto-gen TOC:
{:toc}

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

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

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

Answer 3

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

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

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

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

-##
        -

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

-#
    -

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

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

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

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

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

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

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

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

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

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

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

Answer 4

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

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

Снимки экрана:

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

1. Создать токдля файлов уценки.(Поддержка GitHub Flavored Markdown и Redcarpet)

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

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

Answer 5

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

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

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

Answer 6

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

I предлагаемое Расширение Kramdown TOC и другие возможности для support@github.com и Steven!Ragnarök ответил с обычным:

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

Давайте поднимем этот вопрос до тех пор, пока он не произойдет.

Еще один (обычно неприемлемый) обходной путь - использовать asciidocвместо Markdown , который отображает оглавления .

Answer 7

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

Другой альтернативой Documentup является Flatdoc: http://ricostacruz.com/flatdoc/

Answer 8

Очень удобным способом получения оглавления для файла разметки при работе с кодом Visual Studio является расширение Markdown-TOC .

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

Answer 9

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 ).

Answer 10

Используйте coryfklein / doctoc , форк thlorenz / doctoc , который не добавляет ", созданный с DocToc " для каждой таблицысодержания.

npm install -g coryfklein/doctoc