Сообщить об ошибке.

Расширение toc модуля markdown в Python

Автоматическая генерация оглавления из разметки Markdown

Синтаксис:

import markdown

html = markdown.markdown(some_text, extensions=['toc'])

Параметры:

  • some_text - разметка Markdown,
  • extensions - список расширений модуля.

Возвращаемое значение:

  • текст в формате HTML.

Описание:

Расширение markdown.extensions.toc автоматически генерирует оглавление из разметки Markdown и добавляет его в итоговый HTML-документ.

По умолчанию все заголовки будут автоматически иметь уникальные атрибуты id, созданные на основе текста заголовка. Обратите внимание на этот пример, в котором все три заголовка будут иметь одинаковый идентификатор:

#Header
#Header
#Header

Сгенерирует HTML:

<h1 id="header">Header</h1>
<h1 id="header_1">Header</h1>
<h1 id="header_2">Header</h1>

Для того, что бы разместить оглавление в нужном месте документа Markdown, необходимо в этом месте разместить маркер [TOC]. Затем маркер будет заменен вложенным списком всех заголовков в документе Markdown.

[TOC]

# Header 1

## Header 2

выдаст следующий результат:

<div class="toc">
  <ul>
    <li><a href="#header-1">Header 1</a></li>
      <ul>
        <li><a href="#header-2">Header 2</a></li>
      </ul>
  </ul>
</div>
<h1 id="header-1">Header 1</h1>
<h2 id="header-2">Header 2</h2>

Независимо от того, обнаружен ли в документе маркер (или он отключен), Оглавление доступно как атрибут экземпляра Markdown.toc. Это позволяет вставлять оглавление в другое место в шаблоне страницы. Например:

import markdown
text = """
# Header 1

## Header 2
"""
md = markdown.Markdown(extensions=['toc'])
html = md.convert(text)
print(html)
# <h1 id="header-1">Header 1</h1>
# <h2 id="header-2">Header 2</h2>

toc = md.toc
print(toc)
# <div class="toc">
# <ul>
#    <li><a href="#header-1">Header 1</a>
#       <ul>
#          <li><a href="#header-2">Header 2</a></li>
#       </ul>
#    </li>
# </ul>
# </div>

Также доступен атрибут экземпляра Markdown.toc_tokens, который содержит вложенный список объектов dict. Например, приведенный выше документ приведет к следующему объекту в md.toc_tokens:

print(md.toc_tokens)
# [
#     {
#         'level': 1,
#         'id': 'header-1',
#         'name': 'Header 1',
#         'children': [
#             {'level': 2, 'id': 'header-2', 'name': 'Header 2', 'children':[]}
#         ]
#     }
# ]

Обратите внимание, что level относится к уровню заголовков. Другими словами, h1 - уровень 1, h2 - уровень 2 и т. д. Имейте в виду, что неправильно вложенные уровни на входе могут привести к нечетной вложенности выходных данных.

Переопределение текста оглавления и ссылок на якоря.

В большинстве случаев текст в Оглавлении соответствует тексту заголовка h1-h6. Однако иногда это нежелательно. В этом случае, если это расширение используется вместе с расширением списков атрибутов и в заголовке определен атрибут data-toc-label, то содержимое этого атрибута будет использоваться в качестве текста для элемента в Оглавлении. Например, следующий Markdown:

[TOC]

# Functions

## `markdown.markdown(text [, **kwargs])` { #markdown data-toc-label='markdown.markdown' }

Выдаст следующий результат:

<div class="toc">
  <ul>
    <li><a href="#functions">Functions</a></li>
      <ul>
        <li><a href="#markdown">markdown.markdown</a></li>
      </ul>
  </ul>
</div>
<h1 id="functions">Functions</h1>
<h2 id="markdown"><code>markdown.markdown(text [, **kwargs])</code></h2>

Обратите внимание, что текст в оглавлении намного чище и его легче читать в контексте оглавления. Метка data-toc-label не включается в элемент заголовка HTML. Также обратите внимание, что в списке атрибутов был вручную определен идентификатор id, который обеспечивает более понятный хеш URL-адреса при ссылке на якорь в документе. Если идентификатор не определяется вручную, то он всегда выводится из текста заголовка, а не из атрибута data-toc-label.

Для настройки расширения доступны следующие параметры:

  • marker: текст, который нужно найти и заменить на Оглавление. По умолчанию [TOC]. Установите пустую строку, чтобы отключить поиск маркера, что может сэкономить время, особенно для длинных документов.

  • title: Заголовок для вставки в <div> Оглавления. По умолчанию None.

  • anchorlink: установите значение True, чтобы все заголовки ссылались на самих себя. По умолчанию - False.

  • anchorlink_class: CSS-классы, используемые для ссылки. По умолчанию toclink.

  • permalink: установите значение True или строку для создания постоянных ссылок в конце каждого заголовка. Полезно с таблицами стилей Sphinx.

    Если установлено значение True, то будет использоваться символ абзаца ( или u0026 para;) в качестве текста ссылки. Если задано значение строки, то будет использоваться предоставленная строка.

  • permalink_class: классы CSS, используемые для ссылки. По умолчанию используется headerlink.

  • permalink_title: атрибут заголовка постоянной ссылки. По умолчанию Permanent link.

  • baselevel: Базовый уровень для заголовков. По умолчанию 1.

    Настройка базового уровня позволяет автоматически настраивать уровни заголовков в соответствии с иерархией HTML-шаблонов.

    Например, предположим, что текст Markdown для страницы не должен содержать заголовков выше уровня h3. Для этого необходимо следующее:

    >>>  text = '''
    ... #Some Header
    ... ## Next Level'''
    >>> from markdown.extensions.toc import TocExtension
    >>> html = markdown.markdown(text, extensions=[TocExtension(baselevel=3)])
    >>> print html
    # <h3 id="some_header">Some Header</h3>
    # <h4 id="next_level">Next Level</h4>'
    
  • slugify: вызывается для создания якорей. По умолчанию: markdown.extensions.headerid.slugify. Чтобы использовать другой алгоритм для определения атрибутов id, определите и передайте вызываемый объект, который принимает следующие два аргумента:

    • value: строка, которую нужно объединить.
    • separator: разделитель слов. Символ, заменяющий пробел в id. По умолчанию '-'.

    Вызываемый объект должен возвращать строку, подходящую для использования в атрибутах идентификатора HTML.

    Альтернативная версия вызываемого по умолчанию, поддерживающего строки Unicode, также предоставляется как markdown.extensions.headerid.slugify_unicode.

  • toc_depth: определяет диапазон уровней разделов для включения в Оглавление. Единственное целое число b определяет только нижний уровень раздела h1 .. hb. Строка, состоящая из двух цифр, разделенных дефисом между ними '2-5', определяет верх t и низ b ht .. hb. По умолчанию нижний уровень 6.

    При использовании вместе с базовым уровнем этот параметр не учитывает подобранную иерархию базового уровня. То есть, если и toc_depth, и baselevel равны 3, то в таблице будет присутствовать только самый высокий уровень. Если вы установите baselevel на 3 и toc_depth на 2-6, первым заголовком будет h3, и поэтому он все равно будет включен в Оглавление. Чтобы исключить этот первый уровень, вы должны установить для toc_depth значение 4-6.