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.