import markdown html = markdown.markdown(some_text, extensions=['toc'])
some_text
- разметка Markdown,extensions
- список расширений модуля.Расширение 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
.