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

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

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

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

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

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

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

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

1. Загрузите скрипт https://github.com/ekalinin/github-markdown-toc

2. Накормите README.mdсебя сценарием (как отмечено в статье ЕвгенияREADME.md )

   кот README.md | bash github-markdown-toc

3. Вырежьте и вставьте сгенерированное оглавление и поместите его вверху README.mdфайла.

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

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

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

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

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

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

github-markdown-toc

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

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

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

В настоящее время это невозможно сделать с помощью синтаксиса 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

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

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

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

• когда Jekyll активирован, он по умолчанию генерирует страницы GitHub, используя Kramdown
• Kramdown идет в комплектеTable Of Content . Используйте {:toc}синтаксис. См. Объяснение .

Код 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)).

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

== First ==

== Second ==

В связи с тем, что в 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

вывод: