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

Можно ли создать автоматическое оглавление с помощью Github Flavored Markdown?

Ответ 1

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

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

Монтаж:

npm install -g doctoc

Применение:

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

DocToc WebApp

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

Github Wikis and Anchors

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

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

Ответ 2

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

* auto-gen TOC:
{:toc}

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

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

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

Ответ 3

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

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

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

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

-##
        -

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

-#
    -

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

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

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

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

Удалите неиспользуемые конечные килограммы и начальные тире:

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

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

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

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

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

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

Ответ 4

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

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

Скриншоты:

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

Создайте toc для файлов Markdown. (Поддержка GitHub Flavored Markdown и Redcarpet)
Обновить существующий toc.
Автоматическое обновление toc при сохранении.

Ответ 5

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

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

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

Ответ 6

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

I предложил расширение Kramdown TOC и другие возможности для [email protected] и Стивен! Ragnarök ответил обычным:

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

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

Другим (обычно неприемлемым) решением является использование asciidoc вместо Markdown, который делает TOC.

Ответ 7

Grunt Readme Generator

Я только что написал инструмент для этого. Главным образом для моих проектов github. Это плагин Grunt для создания файла readme из нескольких небольших разделов файлов разметки с оглавлением. Имеет множество функций и настроек.

Цитата из его readme:

...

Предположим, что у вас есть структура readme, такая как:

- Installation
- Usage
    -- Example
    -- Example Output
- Documentation
    -- Options
        --- option1
        --- option2
    -- API
- License
- Contributing

Вы можете написать задачу для генерации Options.md из option1.md и option2.md
Затем задача создания Documentation.md из Options.md и API.md
Другая задача создания Usage.md из Example.md и Example Output.md файлов
И завершите все, создав Readme.md из Installation.md, Usage.md, Documentation.md, License.md и Contributing.md
voilà!

Основные

Автоматическое создание содержимого.
Автоматическое создание Back To Top генерации ссылок
Высоко настраиваемый для многих частей более крупного изображения
Генерация автоматического заголовка и описания вверху
Возможность генерации изображения статуса сборки в верхней части страницы для желаемой ветки
Специально разработан для проектов GitHub и GFM
Дополнительные баннеры сверху, чтобы разместить логотип или искусство ascii!

Для этого плагина требуется Grunt ~0.4.1

....

Надеюсь, это поможет. Репо находится в GitHub. Более подробную информацию о том, как установить и полный список опций, можно найти здесь.

Ответ 8

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

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

Ответ 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');

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

Ответ 10

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

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

Ответ 11

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

npm install -g coryfklein/doctoc

Ответ 12

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

Преимущество над решениями, такими как doctoc, заключается в том, что он интегрируется в редактор виджета GitHub и не нуждается в том, чтобы пользователи работали над своей командной строкой (и требуют от пользователей установки таких инструментов, как node.js). В Chrome он работает с перетаскиванием на страницу "Расширения", в Firefox вам нужно установить расширение GreaseMonkey.

Он будет работать с простой уценкой (т.е. он неправильно обрабатывает кодовые блоки, поскольку это расширение GitHub для уценки). Взносы приветствуются.

Ответ 13

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

Ответ 14

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

Online Таблица Content Generator (raychenon/play-table-of-contents)
arthurhammer/github-toc - расширение браузера, которое добавляет оглавление в репозитории GitHub

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

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

## A

### A2

## B

### B2

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

Ответ 15

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

уценки-TOC

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

Скриншоты:

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

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

Ответ 16

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

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

Если кто-нибудь знает лучший способ сделать эти заключительные замены, добавьте комментарий. Я пробовал разные вещи и не был доволен чем-либо, поэтому я просто сделал это грубо.