Как мне создать какое-то оглавление в вики GitHub?

Question 1

Если вы посмотрите здесь: http://en.wikipedia.org/wiki/Stack_Overflow

Вы заметите, что есть небольшой раздел «Контент», если вы нажмете на одну из ссылок, он отправит вас в определенный раздел на странице.

Как мне это сделать в вики GitHub? С Markdown или чем-то еще?

Question 2

Это хорошо продемонстрировано в Оглавлении Шпаргалки по Markdown .

##### Table of Contents  
[Headers](#headers)  
[Emphasis](#emphasis)  
...snip...    
<a name="headers"/>
## Headers

Если вы наведете курсор на заголовок в файле GitHub Markdown, вы увидите небольшую ссылку слева от него, вы также можете использовать эту ссылку. Формат этой ссылки - <project URL#<header name>. Все <header name>символы должны быть строчными.

Question 3

Одно из возможных (полуавтоматических) решений - Евгений Калинин github-markdown-toc. Этот инструмент, по сути, перебирает ваш README.mdфайл и перебирает #заголовки, чтобы создать оглавление.

Загрузите скрипт https://github.com/ekalinin/github-markdown-toc
Накормите README.mdсебя сценарием (как отмечено в статье ЕвгенияREADME.md )

кот README.md | bash github-markdown-toc
Вырежьте и вставьте сгенерированное оглавление и поместите его вверху README.mdфайла.

Обратите внимание, что эта bashреализация работает только в Linux (насколько я могу судить).

В качестве побочного примечания, есть реализация golang, и, вероятно, больше проблем с работой.

Question 4

Поскольку github не может использовать TOCнапрямую, но у нас есть другие альтернативы.

Вы можете автоматически генерировать оглавление с помощью онлайн-инструмента:

Создайте оглавление из GitHub Markdown или Wiki Online

или через локальный инструмент:

github-markdown-toc

Question 5

https://github.com/jonschlinkert/markdown-toc

git clone your-repo.wiki.git(добавьте .wikiправо перед .gitклонированием вики
npm i -g markdown-toc
Вставьте (с учетом регистра) в уценку вашей вики
markdown-toc -i my-wiki-markdown.md( -iотредактирую на месте)
Прибыль

Обновление: я думаю, что https://github.com/thlorenz/doctoc сейчас более популярен.

Question 6

В настоящее время это невозможно сделать с помощью синтаксиса markdown ( .md). Продолжается неофициальное обсуждение автоматического создания оглавления TOC для визуализированных файлов уценки, таких какREADME.md котором перечислены некоторые идеи.

Однако есть и другие обходные пути, например:

Используйте AsciiDocвместо этого согласно предложению из этого комментария . Например:
```
:toc: macro
:toc-title:
:toclevels: 99
# Title

toc::[]

## A

### A2

## B

### B2
```
Посмотрите пример в littlebits/react-popover( README.adoc) .
Online Table Of Content Generator ( райченон / play-table-of-contents )
arthurhammer / github-toc - расширение браузера, которое добавляет оглавление в репозитории GitHub

Question 7

Если вы не можете придерживаться Markdown , вы можете сделать следующее:

на GitHub / wiki : переключите Markdown на MediaWiki . Используйте __TOC__синтаксис. См. Образец .

на GitHub / repo : переключите Markdown на AsciiDoc . Используйте :toc:синтаксис. См. Демонстрацию .

Однако, используя файлы Markdown в GitHub / repo , вы можете получить его на страницах GitHub, как в Википедии.

когда Jekyll активирован, он по умолчанию генерирует страницы GitHub, используя Kramdown

Kramdown идет в комплектеTable Of Content . Используйте {:toc}синтаксис. См. Объяснение .

Question 8

Код Visual Studio

Если вы используете Visual Studio Code , есть простое в использовании расширение Markdown All in One, которое может мгновенно создать оглавление для любого файла .md.

Просто откройте палитру команд ( Ctrl-Shift-P) ->Markdown: Create Table of Contents

Автообновление портит ваш отредактированный оглавление?

В качестве дополнительного совета вы можете отключить автоматическое обновление оглавления при сохранении с помощью

  "markdown.extension.toc.updateOnSave": false,

в настройках Visual Studio (палитра команд -> Настройки: открыть настройки (JSON)).

Question 9

Вы можете выбрать режим редактирования «MediaWiki», который будет генерировать toc для заголовков, например

== First ==

== Second ==

Question 10

В связи с тем, что в github есть собственный способ создания атрибутов id = ".." в h1, h2, h3 и т. Д. Заголовках в html-версии после обработки Markdown (например, Bitbucket использует немного другой шаблон вставки заголовков заголовков для id = "slug") удобно не изобретать велосипед и использовать библиотеку, которая реконструировала этот процесс.

Я нашел одну неплохую библиотеку для этой задачи под названием markdown-toc .

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

Просто запустите NPX уценки-TOC -i file.md .

И похоже, что это один из самых популярных инструментов для этой задачи - по крайней мере, в экосистеме node.js.

ls
cat <<EOF >> test.md | tee 
## Table of Contents

<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
EOF
ls
cat test.md
npx markdown-toc -i test.md
cat test.md

вывод: