Як створити якийсь зміст у вікі 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файлі та вириває #заголовки, щоб створити TOC.

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безпосередньо, але у нас є інші альтернативи.

Ви можете автоматично генерувати TOC за допомогою Інтернет-інструменту:

Створіть зміст TOC за допомогою GitHub Markdown або Wiki Online

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

github-націнка-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 зараз більш популярний.

Наразі це неможливо зробити за допомогою синтаксису розмітки ( .md). Триває неофіційна дискусія щодо автоматичної генерації змісту TOC для відтворених файлів розмітки, таких як README.mdперелік деяких ідей.

Однак є деякі інші обхідні шляхи, такі як:

• Використовуйте AsciiDocзамість цього згідно з пропозицією цього коментаря . Наприклад:

  :toc: macro
  :toc-title:
  :toclevels: 99
  # Title
  
  toc::[]
  
  ## A
  
  ### A2
  
  ## B
  
  ### B2
  

  Перевірте приклад у littlebits/react-popover( README.adoc) .

• Інтернет- генератор змісту ( raychenon / play-table-of-contents )

• arthurhammer / github-toc - розширення браузера, яке додає зміст до репозиторіїв GitHub

Якщо ви не в змозі дотримуватися Markdown , ви можете зробити наступне :

• на GitHub / wiki : переключіть Markdown на MediaWiki . Використовуйте __TOC__синтаксис. Див. Зразок .
• на GitHub / репо : переключити Markdown на AsciiDoc . Використовуйте :toc:синтаксис. Див. Демо .

Однак, використовуючи файли Markdown у GitHub / repo , ви можете отримати їх на Сторінках GitHub, як у Вікіпедії

• коли Jekyll активовано, він генерує Сторінки GitHub, використовуючи Kramdown за замовчуванням
• Kramdown поставляється з Table Of Content. Використовуйте {:toc}синтаксис. Див . Пояснення .

Код візуальної студії

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

Просто відкрийте Command Palette ( Ctrl-Shift-P) ->Markdown: Create Table of Contents

Автоматичне оновлення зіпсує відредагований TOC?

Як додаткову пораду, ви можете вимкнути "автоматичне оновлення TOC при збереженні", використовуючи

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

у налаштуваннях Visual Studio (Палітра команд -> Налаштування: Відкрити налаштування (JSON)).

Ви можете вибрати режим редагування "MediaWiki", який буде генерувати ток для заголовків, наприклад

== 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

вихід: