Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Admonition extension for Python-Markdown
2# ========================================
4# Adds rST-style admonitions. Inspired by [rST][] feature with the same name.
6# [rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions
8# See https://Python-Markdown.github.io/extensions/admonition
9# for documentation.
11# Original code Copyright [Tiago Serafim](https://www.tiagoserafim.com/).
13# All changes Copyright The Python Markdown Project
15# License: [BSD](https://opensource.org/licenses/bsd-license.php)
18"""
19Adds rST-style admonitions to Python-Markdown.
20Inspired by [rST][] feature with the same name.
22[rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions
24See the [documentation](https://Python-Markdown.github.io/extensions/admonition)
25for details.
26"""
28from __future__ import annotations
30from . import Extension
31from ..blockprocessors import BlockProcessor
32import xml.etree.ElementTree as etree
33import re
34from typing import TYPE_CHECKING
36if TYPE_CHECKING: # pragma: no cover
37 from markdown import blockparser
40class AdmonitionExtension(Extension):
41 """ Admonition extension for Python-Markdown. """
43 def extendMarkdown(self, md):
44 """ Add Admonition to Markdown instance. """
45 md.registerExtension(self)
47 md.parser.blockprocessors.register(AdmonitionProcessor(md.parser), 'admonition', 105)
50class AdmonitionProcessor(BlockProcessor):
52 CLASSNAME = 'admonition'
53 CLASSNAME_TITLE = 'admonition-title'
54 RE = re.compile(r'(?:^|\n)!!! ?([\w\-]+(?: +[\w\-]+)*)(?: +"(.*?)")? *(?:\n|$)')
55 RE_SPACES = re.compile(' +')
57 def __init__(self, parser: blockparser.BlockParser):
58 """Initialization."""
60 super().__init__(parser)
62 self.current_sibling: etree.Element | None = None
63 self.content_indent = 0
65 def parse_content(self, parent: etree.Element, block: str) -> tuple[etree.Element | None, str, str]:
66 """Get sibling admonition.
68 Retrieve the appropriate sibling element. This can get tricky when
69 dealing with lists.
71 """
73 old_block = block
74 the_rest = ''
76 # We already acquired the block via test
77 if self.current_sibling is not None:
78 sibling = self.current_sibling
79 block, the_rest = self.detab(block, self.content_indent)
80 self.current_sibling = None
81 self.content_indent = 0
82 return sibling, block, the_rest
84 sibling = self.lastChild(parent)
86 if sibling is None or sibling.tag != 'div' or sibling.get('class', '').find(self.CLASSNAME) == -1:
87 sibling = None
88 else:
89 # If the last child is a list and the content is sufficiently indented
90 # to be under it, then the content's sibling is in the list.
91 last_child = self.lastChild(sibling)
92 indent = 0
93 while last_child is not None:
94 if (
95 sibling is not None and block.startswith(' ' * self.tab_length * 2) and
96 last_child is not None and last_child.tag in ('ul', 'ol', 'dl')
97 ):
99 # The expectation is that we'll find an `<li>` or `<dt>`.
100 # We should get its last child as well.
101 sibling = self.lastChild(last_child)
102 last_child = self.lastChild(sibling) if sibling is not None else None
104 # Context has been lost at this point, so we must adjust the
105 # text's indentation level so it will be evaluated correctly
106 # under the list.
107 block = block[self.tab_length:]
108 indent += self.tab_length
109 else:
110 last_child = None
112 if not block.startswith(' ' * self.tab_length):
113 sibling = None
115 if sibling is not None:
116 indent += self.tab_length
117 block, the_rest = self.detab(old_block, indent)
118 self.current_sibling = sibling
119 self.content_indent = indent
121 return sibling, block, the_rest
123 def test(self, parent: etree.Element, block: str) -> bool:
125 if self.RE.search(block):
126 return True
127 else:
128 return self.parse_content(parent, block)[0] is not None
130 def run(self, parent: etree.Element, blocks: list[str]) -> None:
131 block = blocks.pop(0)
132 m = self.RE.search(block)
134 if m:
135 if m.start() > 0:
136 self.parser.parseBlocks(parent, [block[:m.start()]])
137 block = block[m.end():] # removes the first line
138 block, theRest = self.detab(block)
139 else:
140 sibling, block, theRest = self.parse_content(parent, block)
142 if m:
143 klass, title = self.get_class_and_title(m)
144 div = etree.SubElement(parent, 'div')
145 div.set('class', '{} {}'.format(self.CLASSNAME, klass))
146 if title:
147 p = etree.SubElement(div, 'p')
148 p.text = title
149 p.set('class', self.CLASSNAME_TITLE)
150 else:
151 # Sibling is a list item, but we need to wrap it's content should be wrapped in <p>
152 if sibling.tag in ('li', 'dd') and sibling.text:
153 text = sibling.text
154 sibling.text = ''
155 p = etree.SubElement(sibling, 'p')
156 p.text = text
158 div = sibling
160 self.parser.parseChunk(div, block)
162 if theRest:
163 # This block contained unindented line(s) after the first indented
164 # line. Insert these lines as the first block of the master blocks
165 # list for future processing.
166 blocks.insert(0, theRest)
168 def get_class_and_title(self, match: re.Match[str]) -> tuple[str, str | None]:
169 klass, title = match.group(1).lower(), match.group(2)
170 klass = self.RE_SPACES.sub(' ', klass)
171 if title is None:
172 # no title was provided, use the capitalized class name as title
173 # e.g.: `!!! note` will render
174 # `<p class="admonition-title">Note</p>`
175 title = klass.split(' ', 1)[0].capitalize()
176 elif title == '':
177 # an explicit blank title should not be rendered
178 # e.g.: `!!! warning ""` will *not* render `p` with a title
179 title = None
180 return klass, title
183def makeExtension(**kwargs): # pragma: no cover
184 return AdmonitionExtension(**kwargs)