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

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

Добавление атрибутов элементов HTML в разметке Markdown

Синтаксис:

import markdown

html = markdown.markdown(text, extensions=['attr_list'])

Параметры:

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

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

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

Описание:

Расширение markdown.extensions.attr_list добавляет синтаксис для определения атрибутов различных элементов HTML в выводе модуля markdown.

Расширение markdown.extensions.attr_list добавляет синтаксис для определения атрибутов различных элементов HTML в выводе markdown.

Пример списка атрибутов может выглядеть так: {: #someid .someclass somekey='some value' }

  • элемент, который начинается с решетки #, устанавливает идентификатор элемента.
  • элемент, который начинается с точки ., будет добавлен в список классов.
  • пара ключ/значение somekey='some value' назначит эту пару элементу.

Имейте в виду, что хотя точечный синтаксис добавляется к class=, использование пар ключ/значение всегда переопределяет ранее определенный атрибут.

{: #id1 .class1 id=id2 class="class2 class3" .class4 }

в итоге выведет

id="id2" class="class2 class3 class4"

HTML включает поддержку того, что некоторые атрибуты могут быть одним термином, например, checked. Следовательно, список атрибутов {: checked} приведет к проверке, если формат вывода - html5, или checked='checked', если формат вывода - xhtml.

Фигурные скобки могут быть экранированы обратной косой чертой, чтобы их нельзя было идентифицировать как список атрибутов: \{ not an attribute list }.

Открывающие и закрывающие фигурные скобки, которые пусты или содержат только пробелы, игнорируются независимо от того, экранированы они или нет.

Двоеточие после открывающей скобки является необязательным, но поддерживается для поддержания согласованности с другими реализациями. Таким образом, следующий список атрибутов также является допустимым:

Пробелы после/перед открывающей/закрывающей скобками необязательны. Они рекомендуются, поскольку улучшают читаемость, но не являются обязательными.

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

Ограничения markdown.extensions.attr_list.

Есть несколько типов элементов, с которыми markdown.extensions.attr_list не работают. Markdown - это подмножество HTML, и все, что не может быть выражено в Markdown, всегда может быть выражено напрямую с помощью HTML.

  • Блоки c кодом: Блоки кода уникальны тем, что они должны отображать синтаксис Markdown. Следовательно, нет способа определить, предназначен ли список атрибутов как часть блока кода или предназначен для определения атрибутов в элементе, оборачивающем этот блок кода. По этой причине расширение игнорирует блоки кода. Для определения атрибутов блоков кода используйте расширения codehilite и fenced code Blocks.
  • Вложенные элементы: Markdown предоставляет механизмы для вложения различных элементов уровня блока в другие элементы. Однако списки атрибутов применяются только к непосредственному родительскому элементу. Невозможно указать, что список атрибутов должен применяться на некотором количестве уровней вверх по дереву документа. Например, при включении списка атрибутов в цитату, список атрибутов всегда применяется только к абзацу, в котором определен список. Невозможно определить атрибуты в самом элементе цитаты.
  • Подразумеваемые элементы: Существуют различные HTML-элементы, которые не представлены в разметке Markdown, а только подразумеваются. Например, элементы ul и ol не существуют в Markdown. Они подразумеваются только наличием элементов списка li. Невозможно использовать расширение markdown.extensions.attr_list для определения атрибутов подразумеваемых элементов, таких как: ul, ol, dl, table, thead, tbody и tr.

Примеры добавления атрибутов в элементы HTML в разметке Markdown.

Чтобы определить атрибуты для элемента уровня блока, список атрибутов должен быть определен в последней строке блока отдельно.

import markdown

text = """
This is a paragraph.
{: #an_id .a_class }
"""

html = markdown.markdown(text, extensions=['attr_list'])
print(html)
# <p class="a_class" id="an_id">This is a paragraph.</p>

Исключение составляют заголовки, так как они разрешены только в одной строке.

import markdown
text = """
A setext style header {: #setext}
=================================

### A hash style header ### {: #hash }
"""
html = markdown.markdown(text, extensions=['attr_list'])
print(html)
# <h1 id="setext">A setext style header</h1>
# <h3 id="hash">A hash style header</h3>

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

import markdown
text = """
[link](http://example.com){: class="foo bar" title="Some title!" }
"""
html = markdown.markdown(text, extensions=['attr_list'])
print(html)
# <p><a href="http://example.com" class="foo bar" title="Some title!">link</a></p>

Если используется [расширение tables][markdown.tables), то атрибуты могут быть определены для ячеек таблицы. Чтобы отличать атрибуты встроенного элемента от атрибутов содержащей его ячейки, список атрибутов должен быть отделен от содержимого по крайней мере одним пробелом и быть определен в конце содержимого ячейки. Поскольку ячейки таблицы могут всегда находиться только в одной строке, то список атрибутов должен оставаться в той же строке, что и содержимое ячейки.

| set on td    | set on em   |
|--------------|-------------|
| *a* { .foo } | *b*{ .foo } |

Приведенный выше пример дает следующий результат:

<table>
  <thead>
    <tr>
      <th>set on td</th>
      <th>set on em</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td class="foo"><em>a</em></td>
      <td><em class="foo">b</em></td>
    </tr>
  </tbody>
</table>

Обратите внимание, что в первом столбце списку атрибутов предшествует пробел; следовательно, он присваивается ячейке таблицы (элемент <td>). Однако во втором столбце перед списком атрибутов не ставится пробел; следовательно, он присваивается встроенному элементу <em>, который непосредственно ему предшествовал.

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