1 # markdown is released under the BSD license 2 # Copyright 2007, 2008 The Python Markdown Project (v. 1.7 and later) 3 # Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b) 4 # Copyright 2004 Manfred Stienstra (the original version) 5 # 6 # All rights reserved. 7 # 8 # Redistribution and use in source and binary forms, with or without 9 # modification, are permitted provided that the following conditions are met: 10 # 11 # * Redistributions of source code must retain the above copyright 12 # notice, this list of conditions and the following disclaimer. 13 # * Redistributions in binary form must reproduce the above copyright 14 # notice, this list of conditions and the following disclaimer in the 15 # documentation and/or other materials provided with the distribution. 16 # * Neither the name of the <organization> nor the 17 # names of its contributors may be used to endorse or promote products 18 # derived from this software without specific prior written permission. 19 # 20 # THIS SOFTWARE IS PROVIDED BY THE PYTHON MARKDOWN PROJECT ''AS IS'' AND ANY 21 # EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 22 # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 23 # DISCLAIMED. IN NO EVENT SHALL ANY CONTRIBUTORS TO THE PYTHON MARKDOWN PROJECT 24 # BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25 # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26 # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27 # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 30 # POSSIBILITY OF SUCH DAMAGE. 31 32 33 """ 34 Admonition extension for Python-Markdown 35 ======================================== 36 37 Adds rST-style admonitions. Inspired by [rST][] feature with the same name. 38 39 The syntax is (followed by an indented block with the contents): 40 !!! [type] [optional explicit title] 41 42 Where `type` is used as a CSS class name of the div. If not present, `title` 43 defaults to the capitalized `type`, so "note" -> "Note". 44 45 rST suggests the following `types`, but you're free to use whatever you want: 46 attention, caution, danger, error, hint, important, note, tip, warning 47 48 49 A simple example: 50 !!! note 51 This is the first line inside the box. 52 53 Outputs: 54 <div class="admonition note"> 55 <p class="admonition-title">Note</p> 56 <p>This is the first line inside the box</p> 57 </div> 58 59 You can also specify the title and CSS class of the admonition: 60 !!! custom "Did you know?" 61 Another line here. 62 63 Outputs: 64 <div class="admonition custom"> 65 <p class="admonition-title">Did you know?</p> 66 <p>Another line here.</p> 67 </div> 68 69 [rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions 70 71 By [Tiago Serafim](http://www.tiagoserafim.com/). 72 73 """ 74 75 from __future__ import absolute_import 76 from __future__ import unicode_literals 77 from . import Extension 78 from ..blockprocessors import BlockProcessor 79 from ..util import etree 80 import re 81 82 83 class AdmonitionExtension(Extension): 84 """ Admonition extension for Python-Markdown. """ 85 86 def extendMarkdown(self, md, md_globals): 87 """ Add Admonition to Markdown instance. """ 88 md.registerExtension(self) 89 90 md.parser.blockprocessors.add('admonition', 91 AdmonitionProcessor(md.parser), 92 '_begin') 93 94 95 class AdmonitionProcessor(BlockProcessor): 96 97 CLASSNAME = 'admonition' 98 CLASSNAME_TITLE = 'admonition-title' 99 RE = re.compile(r'(?:^|\n)!!!\ ?([\w\-]+)(?:\ "(.*?)")?') 100 101 def test(self, parent, block): 102 sibling = self.lastChild(parent) 103 return self.RE.search(block) or \ 104 (block.startswith(' ' * self.tab_length) and sibling and \ 105 sibling.get('class', '').find(self.CLASSNAME) != -1) 106 107 def run(self, parent, blocks): 108 sibling = self.lastChild(parent) 109 block = blocks.pop(0) 110 m = self.RE.search(block) 111 112 if m: 113 block = block[m.end() + 1:] # removes the first line 114 115 block, theRest = self.detab(block) 116 117 if m: 118 klass, title = self.get_class_and_title(m) 119 div = etree.SubElement(parent, 'div') 120 div.set('class', '%s %s' % (self.CLASSNAME, klass)) 121 if title: 122 p = etree.SubElement(div, 'p') 123 p.text = title 124 p.set('class', self.CLASSNAME_TITLE) 125 else: 126 div = sibling 127 128 self.parser.parseChunk(div, block) 129 130 if theRest: 131 # This block contained unindented line(s) after the first indented 132 # line. Insert these lines as the first block of the master blocks 133 # list for future processing. 134 blocks.insert(0, theRest) 135 136 def get_class_and_title(self, match): 137 klass, title = match.group(1).lower(), match.group(2) 138 if title is None: 139 # no title was provided, use the capitalized classname as title 140 # e.g.: `!!! note` will render `<p class="admonition-title">Note</p>` 141 title = klass.capitalize() 142 elif title == '': 143 # an explicit blank title should not be rendered 144 # e.g.: `!!! warning ""` will *not* render `p` with a title 145 title = None 146 return klass, title 147 148 149 def makeExtension(configs={}): 150 return AdmonitionExtension(configs=configs) 151
