Я почав використовувати розмітку, щоб робити нотатки.

Я використовую позначену для перегляду своїх заміток і їх красивих приміток.

Але в міру того, як мої записки стають довше, мені важко знайти те, що я хочу.

Я знаю, що розмітка може створювати таблиці, але чи здатна вона створювати вміст, який переходить до розділів, або визначати розділи сторінок у розмітці?

Крім того, чи є читачі / редактори розмітки, які могли б робити такі дії. Пошук було б хорошою функцією.

Коротше кажучи, я хочу, щоб це було моїм дивовижним інструментом для запису та функцій, як написання книги тощо

MultiMarkdown Composer , схоже, генерує зміст, який допомагає під час редагування.

Також може бути та чи інша бібліотека, яка може генерувати TOC : див . Розширення TOC Python Markdown .

Ви можете спробувати це.

# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)
4. [Fourth Example](#fourth-examplehttpwwwfourthexamplecom)


## Example
## Example2
## Third Example
## [Fourth Example](http://www.fourthexample.com) 

Ось корисний метод. Потрібно створювати посилання, які можна натискати в будь-якому редакторі MarkDown.

# Table of contents
1. [Introduction](#introduction)
2. [Some paragraph](#paragraph1)
    1. [Sub paragraph](#subparagraph1)
3. [Another paragraph](#paragraph2)

## This is the introduction <a name="introduction"></a>
Some introduction text, formatted in heading 2 style

## Some paragraph <a name="paragraph1"></a>
The first paragraph text

### Sub paragraph <a name="subparagraph1"></a>
This is a sub paragraph, formatted in heading 3 style

## Another paragraph <a name="paragraph2"></a>
The second paragraph text

Виробляє:

Зміст

1. Вступ
2. Якийсь абзац
   1. Підпункт
3. Ще один абзац

Це вступ

Деякі вступні тексти, відформатовані у стилі заголовка 2

Якийсь абзац

Текст першого абзацу

Підпункт

Це підпункт, відформатований у стилі заголовка 3

Ще один абзац

Текст другого абзацу

Для користувачів Visual Studio Code корисною ідеєю є використання плагіна Markdown TOC .

Щоб встановити його, запустіть швидкий відкритий код VS Code ( Control/⌘+ P), вставте наступну команду та натисніть клавішу Enter.

ext install markdown-toc

А щоб створити TOC, відкрийте палітру команд ( Control/⌘+ Shift+ P) та виберіть Markdown TOC:Insert/Update optionабо використовуйте Control/⌘+ MT.

Ви можете спробувати цей сценарій рубіну для створення TOC з файлу розмітки.

 #!/usr/bin/env ruby

require 'uri'

fileName = ARGV[0]
fileName = "README.md" if !fileName

File.open(fileName, 'r') do |f|
  inside_code_snippet = false
  f.each_line do |line|
    forbidden_words = ['Table of contents', 'define', 'pragma']
    inside_code_snippet = !inside_code_snippet if line.start_with?('```')
    next if !line.start_with?("#") || forbidden_words.any? { |w| line =~ /#{w}/ } || inside_code_snippet

    title = line.gsub("#", "").strip
    href = URI::encode title.gsub(" ", "-").downcase
    puts "  " * (line.count("#")-1) + "* [#{title}](\##{href})"
  end
end

Є два способи створити свій TOC (підсумок) у своєму документі про розмітку.

1. Вручну

# My Table of content
- [Section 1](#id-section1)
- [Section 2](#id-section2)

<div id='id-section1'/>
## Section 1
<div id='id-section2'/>
## Section 2

2. Програмно

Ви можете використовувати, наприклад, скрипт, який генерує для вас резюме, подивіться на мій проект на github - summarizeMD -

Я спробував також інший модуль скрипт / npm (наприклад, doctoc ), але ніхто не відтворював TOC з працюючими якорями.

# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)

## Example [](#){name=example}
## Example2 [](#){name=example2}
## [Third Example](#){name=third-example}

Якщо ви додатково використовуєте розмітку, не забудьте додати спеціальні атрибути до посилань, заголовків, кодових огорож та зображень.
https://michelf.ca/projects/php-markdown/extra/#spe-attr

Якірні теги, згенеровані різними аналізаторами Markdown, не є рівними.

Якщо ви працюєте з аналізаторами Markdown GFM (GitHub Flavored Markdown) або Redcarpet, я написав плагін Vim для обробки змісту.

Особливості

1. Створення вмісту для файлів Markdown.

   Підтримувані парсери Markdown:

   • GFM (GitHub ароматизована знижка)
   • Червоний килим

2. Оновіть існуючий зміст.

3. Автоматичне оновлення наявного вмісту при збереженні.

Скріншоти

Використання

Створити зміст

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

1. :GenTocGFM

   Створення вмісту у стилі посилання GFM.

   Ця команда підходить для файлів Markdown у сховищах GitHub, таких як README.md та файлів Markdown для GitBook.

2. :GenTocRedcarpet

   Створення вмісту в стилі Redcarpet.

   Ця команда підходить для того, як Джекілл або деінде використовуватиме Redcarpet як його аналізатор Markdown.

   Ви можете подивитися тут , щоб дізнатися різницю між GFM і Redcarpet стиль змісту посилання.

Оновіть наявний вміст вручну

Зазвичай вам цього не потрібно, існуючий вміст автоматично оновиться при збереженні за замовчуванням. Якщо ви хочете зробити це вручну, просто використовуйте :UpdateTocкоманду.

Завантаження та документи

https://github.com/mzlogin/vim-markdown-toc

Крім того, можна використовувати pandoc, в «швейцарський армійський ніж» для перетворення « з одного формату в інший розмітки» . Він може автоматично генерувати вміст у вихідному документі, якщо ви надаєте --tocаргумент.

Підказка: Якщо вам потрібна таблиця вмісту у htmlвиведенні, вам також потрібно надати, -sякий створює окремий документ.

Приклад командного рядка оболонки:

./pandoc -s --toc input.md -o output.html

На користь тих, хто створює README.mdфайли в Atom (як я знайшов цю тему):

apm install markdown-toc

https://atom.io/packages/markdown-toc

Якщо ви хочете використовувати інструмент javascript / node.js, перегляньте позначку-toc .

Ви можете генерувати його за допомогою цього bash однолінійного. Припускає, що ваш файл розмітки викликається FILE.md.

echo "## Contents" ; echo ; 
cat FILE.md | grep '^## ' | grep -v Contents | sed 's/^## //' | 
  while read -r title ; do 
    link=$(echo $title | tr 'A-Z ' 'a-z-') ; 
    echo "- [$title](#$link)" ; 
    done

Я щойно зашифрував розширення для python-markdown, яке використовує його аналізатор для отримання заголовків, і виводить TOC у вигляді формату Markdown, не упорядкованого списку з локальними посиланнями. Файл є

• md_toc.py (був md_toc.py )

... і його слід розмістити в markdown/extensions/каталозі в установці розмітки. Потім все, що вам потрібно зробити, - ввести <a>теги прив’язки з id="..."атрибутом як посиланням - так що для вхідного тексту на зразок цього:

$ cat test.md 
Hello
=====

## <a id="sect one"></a>SECTION ONE ##

something here

### <a id='sect two'>eh</a>SECTION TWO ###

something else

#### SECTION THREE

nothing here

### <a id="four"></a>SECTION FOUR

also...

... розширення можна назвати так:

$ python -m markdown -x md_toc test.md 
* Hello
    * [SECTION ONE](#sect one)
        * [SECTION TWO](#sect two)
            * SECTION THREE
        * [SECTION FOUR](#four)

... а потім ви можете вставити цей ток у свій документ розмітки (або мати ярлик у своєму текстовому редакторі, який викликає скрипт у відкритому документі, а потім вставляє отриманий TOC у той самий документ).

Зверніть увагу , що більш старі версії python-markdownне мають __main__.pyмодуль, і як такий, командний рядок виклику , як зазначено вище , не працюватиме для цих версій.

Як згадується в інших відповідях, існує декілька способів автоматичного створення змісту. Більшість є програмним забезпеченням з відкритим кодом і може бути адаптоване до ваших потреб.

Однак мені не вистачало візуально привабливого форматування змісту з використанням обмежених варіантів, які надає Markdown. Ми придумали наступне:

Код

## Content

**[1. Markdown](#heading--1)**

  * [1.1. Markdown formatting cheatsheet](#heading--1-1)
  * [1.2. Markdown formatting details](#heading--1-2)

**[2. BBCode formatting](#heading--2)**

  * [2.1. Basic text formatting](#heading--2-1)

      * [2.1.1. Not so basic text formatting](#heading--2-1-1)

  * [2.2. Lists, Images, Code](#heading--2-2)
  * [2.3. Special features](#heading--2-3)

----

Всередині вашого документа ви розміщуєте цільові маркери підрозділу таким чином:

<div id="heading--1-1"/>
### 1.1. Markdown formatting cheatsheet

Залежно від того, де і як ви використовуєте Markdown, слід також працювати наступне і надавати приємніший вигляд коду Markdown:

### 1.1. Markdown formatting cheatsheet <a name="heading--1-1"/>

Приклад надання

Зміст

1. Відмітка

• 1.1. Шаблон для форматування розмітки
• 1.2. Деталі форматування розмітки

2. Форматування BBCode

• 2.1. Основне форматування тексту

  • 2.1.1. Не так базове форматування тексту

• 2.2. Списки, зображення, код

• 2.3. Особливості

---

Переваги

• Ви можете додати стільки рівнів глав і підрозділів, скільки вам потрібно. У змісті вони відображатимуться як вкладені не упорядковані списки на більш глибоких рівнях.

• Немає використання упорядкованих списків. Це створило б відступ, не пов'язувало б число і не може використовуватися для створення десяткової класифікаційної нумерації типу "1.1.".

• Немає використання списків першого рівня. Тут використання не упорядкованого списку можливо, але не обов’язково: відступ і куля просто додають тут візуального скупчення і ніякої функції, тому ми не використовуємо список для першого рівня ToC взагалі.

• Візуальний акцент на розділах першого рівня в змісті зміцнено жирним шрифтом.

• Короткі, значущі маркери підрозділів, які виглядають «красиво» в URL-адресі браузера, наприклад, як #heading--1-1маркери, що містять перетворені фрагменти фактичного заголовка.

• Код використовує заголовки H2 ( ## …) для розділів, H3 - заголовки ( ### …) для підзаголовків тощо. Це полегшує читання вихідного коду, оскільки ## …забезпечує більш чітку візуальну підказку при прокручуванні порівняно з випадком, коли розділи починатимуться з заголовків H1 ( # …). Це все ще логічно послідовно, оскільки ви використовуєте заголовок H1 для самого заголовка документа.

• Нарешті, ми додаємо приємне горизонтальне правило для відокремлення змісту від фактичного вмісту.

Докладніше про цю техніку та те, як ми її використовуємо всередині форуму програмного дискурсу , дивіться тут .

Я написав сценарій python, який аналізує файл розмітки та видає вміст у вигляді списку відміток: md-to-toc

На відміну від інших знайдених мною скриптів, md-to-to правильно підтримує повторювані заголовки. Він також не потребує підключення до Інтернету, тому він працює на будь-якому файлі md, не тільки на доступному у публічному репо.

У коді Visual Studio (VSCode) ви можете використовувати розширення Markdown All in One .

Після встановлення виконайте наведені нижче дії.

1. Натисніть CTRL+ SHIFT+P
2. Виберіть Розмітка: Створити зміст

Я щойно почав робити те ж саме (робити нотатки в Markdown). Я використовую Sublime Text 2 із плагіном MarkdownPreview . Вбудований аналізатор розмітки підтримує [TOC].

Typora створює Зміст , додаючи [TOC]до свого документа.

У Gitlab розмітка підтримує це: [[_TOC_]]

Просто використовуйте текстовий редактор за допомогою плагіна.

Ваш редактор, цілком можливо, має пакунок / плагін для вирішення цього питання. Наприклад, в Emacs можна встановити генератор TOC markdown-toc . Потім, редагуючи, просто неодноразово телефонуйте M-x markdown-toc-generate-or-refresh-toc. Цього варто зробити ключовим обов'язковим, якщо ви хочете робити це часто. Добре генерувати простий TOC, не забруднюючи свого документа HTML-якорями.

Інші редактори мають подібні плагіни, тому популярний список має щось на зразок:

• Emacs : позначка-toc
• Vim : відмітка-toc
• Atom : відмітка-toc
• VSCode : відмітка -toc

На основі відповіді альбертодебортолі створена функція з додатковими перевірками та підстановкою розділових знаків.

# @fn       def generate_table_of_contents markdown # {{{
# @brief    Generates table of contents for given markdown text
#
# @param    [String]  markdown Markdown string e.g. File.read('README.md')
#
# @return   [String]  Table of content in markdown format.
#
def generate_table_of_contents markdown
  table_of_contents = ""
  i_section = 0
  # to track markdown code sections, because e.g. ruby comments also start with #
  inside_code_section = false
  markdown.each_line do |line|
    inside_code_section = !inside_code_section if line.start_with?('```')

    forbidden_words = ['Table of contents', 'define', 'pragma']
    next if !line.start_with?('#') || inside_code_section || forbidden_words.any? { |w| line =~ /#{w}/ }

    title = line.gsub("#", "").strip
    href = title.gsub(/(^[!.?:\(\)]+|[!.?:\(\)]+$)/, '').gsub(/[!.,?:; \(\)-]+/, "-").downcase

    bullet = line.count("#") > 1 ? " *" : "#{i_section += 1}."
    table_of_contents << "  " * (line.count("#") - 1) + "#{bullet} [#{title}](\##{href})\n"
  end
  table_of_contents
end

MultiMarkdown 4.7 має макрос {{TOC}}, який вставляє зміст.

Для мене рішення, запропоноване @Tum, працює як шарм для змісту з 2 рівнями. Однак для 3-го рівня це не спрацювало. Він не відображав посилання, як для перших двох рівнів, він відображає звичайний текст 3.5.1. [bla bla bla](#blablabla) <br>.

Моє рішення - це доповнення до рішення @Tum (що дуже просто) для людей, які потребують змісту з 3 рівнями або більше.

На другому рівні проста вкладка зробить відступ правильно для вас. Але він не підтримує 2 вкладки. Натомість вам потрібно скористатися однією вкладкою та додати стільки,  скільки потрібно, щоб правильно вирівняти 3-й рівень.

Ось приклад із використанням 4 рівнів (чим вище рівень, тим жахливо стає):

# Table of Contents
1. [Title](#title) <br>
    1.1. [sub-title](#sub_title) <br>
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.1. [sub-sub-title](#sub_sub_title)
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.1.1. [sub-sub-sub-title](#sub_sub_sub_title)

# Title <a name="title"></a>
Heading 1

## Sub-Title <a name="sub_title"></a>
Heading 2

### Sub-Sub-Title <a name="sub_sub_title"></a>
Heading 3

#### Sub-Sub-Sub-Title <a name="sub_sub_sub_title"></a>
Heading 4

Це дає наступний результат, коли кожен елемент змісту є посиланням на відповідний розділ. Зверніть увагу також на те <br>, щоб додати новий рядок, а не в тому ж рядку.

Зміст

1. Назва
   1.1. Підзаголовок
          1.1.1. Підзаголовок
                    1.1.1.1. Під-підзаголовок

Назва

Заголовок 1

Підзаголовок

Заголовок 2

Підзаголовок

Заголовок 3

Заголовок 4

Залежно від вашого робочого процесу, ви, можливо, захочете ознайомитись з розшаруванням

Це роздріб оригіналу ( http://strapdownjs.com ), який додає покоління змісту.

На репо є файл конфігурації apache (можливо, його ще не оновлювали належним чином) для завершення простої відмітки на льоту, якщо ви не хочете писати в HTML-файли.

Я не впевнений, яка офіційна документація щодо розмітки. Перехресне посилання можна писати просто в дужках [Heading]або з порожніми дужками [Heading][].

Обидва працюють за допомогою pandoc . Тому я створив швидкий скрипт bash, який замінить $ TOC у md-файлі своїм TOC. (Вам знадобиться envsubst, який може не входити до вашого дистрибутива)

#!/bin/bash
filename=$1
__TOC__=$(grep "^##" $filename | sed -e 's/ /1. /;s/^##//;s/#/   /g;s/\. \(.*\)$/. [\1][]/')
export __TOC__
envsubst '$__TOC__' < $filename

Якщо ви скористаєтеся Eclipse, ви можете скористатися ярликом Ctrl+ O(контур), це покаже еквівалент вмісту та дозволить шукати в заголовках розділів (автозаповнення).

Ви також можете відкрити подання контуру (Вікно -> Показати перегляд -> Контур), але в ньому немає автоматичного завершення пошуку.

Використовуйте toc.py, який являє собою крихітний сценарій пітона, який генерує зміст для вашого розмітки.

Використання:

• У файл Markdown додайте <toc>туди, де ви хочете розмістити вміст.
• $python toc.py README.md(Використовуйте назву файлу розмітки замість README.md )

Ура!

Я використав https://github.com/ekalinin/github-markdown-toc, яка забезпечує утиліту командного рядка, яка автоматично генерує вміст із документа розмітки.

Ні плагінів, ні макросів, ні інших залежностей. Після встановлення утиліти просто вставте висновок утиліти на місце в документі, куди потрібно вміст. Дуже простий у використанні.

$ cat README.md | ./gh-md-toc -

Якщо ваш файл Markdown повинен відображатися в репортажі на bitbucket.org, вам слід додати [TOC]місце, де ви хочете свою таблицю вмісту. Потім він буде автоматично генерований. Більше інформації тут:

https://confluence.atlassian.com/bitbucket/add-a-table-of-contents-to-a-wiki-221451163.html

Існує сценарій Ruby під назвою mdtoc.rb, який може автоматично генерувати Зміст GFM Markdown, і він схожий, але трохи відрізняється від інших скриптів, розміщених тут.

Дано вхідний файл відмітки:

# Lorem Ipsum

Lorem ipsum dolor sit amet, mei alienum adipiscing te, has no possit delicata. Te nominavi suavitate sed, quis alia cum no, has an malis dictas explicari. At mel nonumes eloquentiam, eos ea dicat nullam. Sed eirmod gubergren scripserit ne, mei timeam nonumes te. Qui ut tale sonet consul, vix integre oportere an. Duis ullum at ius.

## Et cum

Et cum affert dolorem habemus. Sale malis at mel. Te pri copiosae hendrerit. Cu nec agam iracundia necessitatibus, tibique corpora adipisci qui cu. Et vix causae consetetur deterruisset, ius ea inermis quaerendum.

### His ut

His ut feugait consectetuer, id mollis nominati has, in usu insolens tractatos. Nemore viderer torquatos qui ei, corpora adipiscing ex nec. Debet vivendum ne nec, ipsum zril choro ex sed. Doming probatus euripidis vim cu, habeo apeirian et nec. Ludus pertinacia an pro, in accusam menandri reformidans nam, sed in tantas semper impedit.

### Doctus voluptua

Doctus voluptua his eu, cu ius mazim invidunt incorrupte. Ad maiorum sensibus mea. Eius posse sonet no vim, te paulo postulant salutatus ius, augue persequeris eum cu. Pro omnesque salutandi evertitur ea, an mea fugit gloriatur. Pro ne menandri intellegam, in vis clita recusabo sensibus. Usu atqui scaevola an.

## Id scripta

Id scripta alterum pri, nam audiam labitur reprehendunt at. No alia putent est. Eos diam bonorum oportere ad. Sit ad admodum constituto, vide democritum id eum. Ex singulis laboramus vis, ius no minim libris deleniti, euismod sadipscing vix id.

Він генерує цю зміст:

$ mdtoc.rb FILE.md 
#### Table of contents

1. [Et cum](#et-cum)
    * [His ut](#his-ut)
    * [Doctus voluptua](#doctus-voluptua)
2. [Id scripta](#id-scripta)

Дивіться також мій пост в блозі на цю тему.