Уценка для создания страниц и оглавления?


359

Я начал использовать уценку, чтобы делать заметки.

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

Но поскольку мои записи становятся длиннее, мне становится трудно найти то, что я хочу.

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

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

Короче говоря, я хочу сделать его своим замечательным инструментом для создания заметок и функций, таких как написание книги и т. Д.


2
если вы хотите использовать инструмент javascript / node.js, попробуйте
mark

@jonschlinkert Вы должны представить это как ответ! В настоящее время ответы предлагают только инструменты, которые не являются бесплатными или Python. Не очень хороший выбор.
Доми

8
Я должен упомянуть, что в LaTeX это достигается с помощью \tableofcontents. Если колесо будет изобретено заново, предпочтительнее будет скопировать хорошие детали.
Ээро Аалтонен


Точно так же reStructuredText имеет встроенную директиву для оглавления, которая в простейшем виде выглядит просто .. contents::.
Saaj

Ответы:


37

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

Также может существовать та или иная библиотека, которая может генерировать оглавления : см. Расширение оглавления Python Markdown .


17
MultiMarkdown Composer предназначен только для MacOS
chmike

1
Работающий Python Markdown TOC ссылка: python-markdown.github.io/extensions/toc
Джон

2
Приложение не доступно в регионе Великобритании.
Кенорб

Расширение TOC создает HTML-коды, а не Markdown. Примечательно, что это сложно.
Рюрни

396

Вы можете попробовать это.

# 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) 

10
3-й пример выше не работает. ## Example ## "Example2" ## Third Example<a name="third-example" /> это единственный способ, которым я мог заставить его глотать пространства до сих пор. Конечно, третий тег будет интерпретирован как - #Third- с последующим пробелом - затем словом Пример - в вашем фрагменте выше? Дефисы не работают вообще. Спасибо
два боба

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

6
Прекрасно работает в RStudio. Сразу хочу добавить, что немецкие умлауты, например ü, должны быть написаны без умлаута в якоре, т. 1. [Einführung](#einfuhrung)
Е.

4
Якоря не создаются автоматически для заголовков в Bitbucket v4.5.2
Майк Райландер,

1
Четвертый пример - это то, что я искал. Спасибо!
kenecaswell

221

Вот полезный метод. Должен производить кликабельные ссылки в любом редакторе 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

Еще один абзац

Второй абзац текста


23
Мне нравится размещать тег привязки на строке над заголовком, чтобы при нажатии на ссылку заголовок отображался на странице.
mgarey

4
Это был единственный полезный для меня. С длинными заголовками это невозможно сделать без тегов привязки.
Мэтт Флетчер

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

@mgarey Просто поставь якорь первым:## <a name="foo" /> Foo
tobias_k

40

Для пользователей кода Visual Studio хорошая идея - использовать плагин Markdown TOC .

Чтобы установить его, запустите VS Code Quick Open ( Control/⌘+ P), вставьте следующую команду и нажмите ввод.

ext install markdown-toc

А для генерации оглавления откройте командную палитру ( Control/⌘+ Shift+ P) и выберите Markdown TOC:Insert/Update optionили используйте Control/⌘+ MT.


7
Примечание: я только что обнаружил, что с помощью стандартного VSCode вы можете сделать ссылки на уценку к заголовкам:, [Section Foo](#foo-header-title)и это даже работает вне режима предварительного просмотра (то есть в простой уценке).
kitsu.eb

4
другая альтернатива для VSCode - vscode-markdown, которая имеет несколько функций, в том числе
ToC

26

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

 #!/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

Большой! Просто примечание, может захотеть добавить ifndef, includeи endif, среди других директив препроцессора, в список запрещенных слов. Кроме того, определение списка вне области действия цикла избавляет от необходимости повторного создания его с каждой итерацией. Кроме того, это подберет комментарии любого языка, который использует #синтаксис комментариев, включая Ruby, что не очень хорошо. Я готов отредактировать, если хотите. Однако это отличное начало и хорошо сработало для моих целей. Спасибо!
Джефф Кляйн

Это работает только с заголовками atx (то есть теми, которые начинаются с #), а не с setext (подчеркнутыми).
gozzilli

спасибо за это, если вы используете это для красной каретки на рельсах, вы должны пойти title.parameterizeна href, спасибо!
Алексис

25

Существует два способа создания оглавления (резюме) в документе уценки.

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

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


`` <div id = ... `не распознается MarkdownPad2 (Windows)
chmike

Работает только в той же папке, также не работает для заголовков setext.
gozzilli

25
# 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}

Если вы используете markdown extra, не забудьте добавить специальные атрибуты в ссылки, заголовки, заборы кода и изображения.
https://michelf.ca/projects/php-markdown/extra/#spe-attr


11

Якорные теги, созданные разными парсерами Markdown, не являются четными.

Если вы работаете с анализаторами Markdown GFM (GitHub Flavored Markdown) или Redcarpet, я написал плагин Vim для обработки оглавления.

особенности

  1. Создайте оглавление для файлов Markdown.

    Поддерживаемые парсеры Markdown:

    • GFM (GitHub Flavored Markdown)
    • Красный ковер
  2. Обновить существующее оглавление.

  3. Автоматическое обновление существующего оглавления при сохранении.

Скриншоты

ВИМ-уценки-TOC

Применение

Создать оглавление

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

  1. :GenTocGFM

    Создайте оглавление в стиле ссылки GFM.

    Эта команда подходит для файлов Markdown в репозиториях GitHub, таких как README.md, и файлов Markdown для GitBook.

  2. :GenTocRedcarpet

    Создайте оглавление в стиле ссылки Redcarpet.

    Эта команда подходит для Jekyll или где-либо еще, использующего Redcarpet в качестве парсера Markdown.

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

Обновить существующее оглавление вручную

Как правило, вам не нужно этого делать, существующее оглавление будет автоматически обновляться при сохранении по умолчанию. Если вы хотите сделать это вручную, просто используйте :UpdateTocкоманду.

Загрузки и документы

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


10

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

Подсказка: если вы хотите оглавление в htmlвыводе, вам также необходимо указать, -sкакой из них генерирует отдельный документ.

Пример командной строки оболочки:

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



7

Вы можете сгенерировать его, используя эту строку. Предполагается, что ваш файл уценки называется 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

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

6

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

... и это должно быть помещено в 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)

... и затем вы можете вставить этот ток в свой документ уценки (или иметь ярлык в текстовом редакторе, который вызывает скрипт в текущем открытом документе, а затем вставляет полученное оглавление в тот же документ).

Обратите внимание, что более старые версии python-markdownне имеют __main__.pyмодуля, и, следовательно, вызов командной строки, как указано выше, не будет работать для этих версий.


6

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

Однако мне не хватало визуально привлекательного форматирования оглавления с использованием ограниченных параметров, предоставляемых 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. Уценка

2. Форматирование BBCode


преимущества

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

  • Нет использования упорядоченных списков. Они создали бы отступ, не связали бы номер и не могут быть использованы для создания десятичной классификационной нумерации, такой как «1.1.».

  • Нет использования списков для первого уровня. Здесь использование неупорядоченного списка возможно, но не обязательно: отступы и маркеры просто добавляют визуальный беспорядок и здесь никакой функции, поэтому мы вообще не используем список для первого уровня ToC.

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

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

  • В коде используются заголовки H2 ( ## …) для разделов, заголовки H3 ( ### …) для подзаголовков и т. Д. Это облегчает чтение исходного кода, поскольку ## …обеспечивает более четкую визуальную подсказку при прокрутке по сравнению со случаем, когда разделы начинаются с заголовков H1 ( # …). Это все еще логически непротиворечиво, поскольку вы используете заголовок H1 для самого заголовка документа.

  • Наконец, мы добавляем хорошее горизонтальное правило, чтобы отделить оглавление от фактического содержания.

Подробнее об этой методике и о том, как мы ее используем в форуме Discourse , см. Здесь .


5

Я написал скрипт Python, который анализирует файл уценки и выводит оглавление в виде списка уценки: md-to-toc

В отличие от других скриптов, которые я нашел, md-to-toc правильно поддерживает дубликаты заголовков. Он также не требует подключения к Интернету, поэтому он работает с любым md-файлом, а не только с теми, которые доступны в публичном репо.


5

В Visual Studio Code (VSCode) вы можете использовать расширение Markdown All in One .

После установки выполните следующие действия:

  1. Нажмите CTRL+ SHIFT+P
  2. Выберите Markdown: Создать оглавление




4

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

Ваш редактор вполне может иметь пакет / плагин, чтобы справиться с этим для вас. Например, в Emacs вы можете установить генератор TOC markdown-toc . Затем, как вы редактируете, просто несколько раз позвоните M-x markdown-toc-generate-or-refresh-toc. Это стоит связывания ключей, если вы хотите делать это часто. Хорошо генерировать простое оглавление без загрязнения документа HTML-якорями.

Другие редакторы имеют похожие плагины, поэтому популярный список выглядит примерно так:


2

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

# @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


2

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

Мое решение - это дополнение к решению @Tum (которое очень просто) для людей, которым нужно оглавление с 3 уровнями или более.

На втором уровне простая вкладка правильно сделает отступ для вас. Но он не поддерживает 2 вкладки. Вместо этого вы должны использовать одну вкладку и добавлять столько, &nbsp;сколько вам нужно, чтобы правильно выровнять 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. Sub-подзаголовок
                     1.1.1.1. Sub-Sub-подзаголовок

заглавие

Заголовок 1

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

Заголовок 2

Sub-подзаголовок

Заголовок 3

Sub-Sub-подзаголовок

Заголовок 4


1

В зависимости от вашего рабочего процесса, вы можете посмотреть на страпдаун

Это форк оригинала ( http://strapdownjs.com ), который добавляет генерацию таблицы содержания.

В репозитории есть конфигурационный файл apache (возможно, он еще не обновлен должным образом), чтобы обернуть простую уценку на лету, если вы предпочитаете не писать в html-файлы.


1

Я не уверен, какова официальная документация для уценки. Перекрестная ссылка может быть написана только в квадратных скобках [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

1

Если вы используете Eclipse, вы можете использовать ярлык Ctrl+ O(контур), это покажет эквивалент оглавления и позволит искать в заголовках разделов (автозаполнение).

Вы также можете открыть представление Outline (Окно -> Показать представление -> Outline), но в нем нет автозаполненного поиска.


1

Используйте toc.py, который представляет собой крошечный скрипт на python, который генерирует оглавление для вашей уценки.

Применение:

  • В вашем файле Markdown добавьте, <toc>куда вы хотите поместить оглавление.
  • $python toc.py README.md(Используйте имя файла уценки вместо README.md )

Ура!


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

1

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

Нет плагинов, или макросов или других зависимостей. После установки утилиты просто вставьте выходные данные утилиты в то место документа, в котором вы хотите найти оглавление. Очень прост в использовании.

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


1

Существует скрипт Ruby с именем mdtoc.rb, который может автоматически генерировать оглавление GFM Markdown, и он похож, но немного отличается от некоторых других скриптов, размещенных здесь.

Имеется входной файл 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)

Смотрите также мой пост в блоге на эту тему.

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.