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 HeaderID Extension for Python-Markdown 35 ====================================== 36 37 Auto-generate id attributes for HTML headers. 38 39 Basic usage: 40 41 >>> import markdown 42 >>> text = "# Some Header #" 43 >>> md = markdown.markdown(text, ['headerid']) 44 >>> print md 45 <h1 id="some-header">Some Header</h1> 46 47 All header IDs are unique: 48 49 >>> text = ''' 50 ... #Header 51 ... #Header 52 ... #Header''' 53 >>> md = markdown.markdown(text, ['headerid']) 54 >>> print md 55 <h1 id="header">Header</h1> 56 <h1 id="header_1">Header</h1> 57 <h1 id="header_2">Header</h1> 58 59 To fit within a html template's hierarchy, set the header base level: 60 61 >>> text = ''' 62 ... #Some Header 63 ... ## Next Level''' 64 >>> md = markdown.markdown(text, ['headerid(level=3)']) 65 >>> print md 66 <h3 id="some-header">Some Header</h3> 67 <h4 id="next-level">Next Level</h4> 68 69 Works with inline markup. 70 71 >>> text = '#Some *Header* with [markup](http://example.com).' 72 >>> md = markdown.markdown(text, ['headerid']) 73 >>> print md 74 <h1 id="some-header-with-markup">Some <em>Header</em> with <a href="http://example.com">markup</a>.</h1> 75 76 Turn off auto generated IDs: 77 78 >>> text = ''' 79 ... # Some Header 80 ... # Another Header''' 81 >>> md = markdown.markdown(text, ['headerid(forceid=False)']) 82 >>> print md 83 <h1>Some Header</h1> 84 <h1>Another Header</h1> 85 86 Use with MetaData extension: 87 88 >>> text = '''header_level: 2 89 ... header_forceid: Off 90 ... 91 ... # A Header''' 92 >>> md = markdown.markdown(text, ['headerid', 'meta']) 93 >>> print md 94 <h2>A Header</h2> 95 96 Copyright 2007-2011 [Waylan Limberg](http://achinghead.com/). 97 98 Project website: <http://packages.python.org/Markdown/extensions/header_id.html> 99 Contact: markdown@freewisdom.org 100 101 License: BSD (see ../docs/LICENSE for details) 102 103 Dependencies: 104 * [Python 2.3+](http://python.org) 105 * [Markdown 2.0+](http://packages.python.org/Markdown/) 106 107 """ 108 109 from __future__ import absolute_import 110 from __future__ import unicode_literals 111 from . import Extension 112 from ..treeprocessors import Treeprocessor 113 import re 114 import logging 115 import unicodedata 116 117 logger = logging.getLogger('MARKDOWN') 118 119 IDCOUNT_RE = re.compile(r'^(.*)_([0-9]+)$') 120 121 122 def slugify(value, separator): 123 """ Slugify a string, to make it URL friendly. """ 124 value = unicodedata.normalize('NFKD', value).encode('ascii', 'ignore') 125 value = re.sub('[^\w\s-]', '', value.decode('ascii')).strip().lower() 126 return re.sub('[%s\s]+' % separator, separator, value) 127 128 129 def unique(id, ids): 130 """ Ensure id is unique in set of ids. Append '_1', '_2'... if not """ 131 while id in ids or not id: 132 m = IDCOUNT_RE.match(id) 133 if m: 134 id = '%s_%d'% (m.group(1), int(m.group(2))+1) 135 else: 136 id = '%s_%d'% (id, 1) 137 ids.add(id) 138 return id 139 140 141 def itertext(elem): 142 """ Loop through all children and return text only. 143 144 Reimplements method of same name added to ElementTree in Python 2.7 145 146 """ 147 if elem.text: 148 yield elem.text 149 for e in elem: 150 for s in itertext(e): 151 yield s 152 if e.tail: 153 yield e.tail 154 155 156 class HeaderIdTreeprocessor(Treeprocessor): 157 """ Assign IDs to headers. """ 158 159 IDs = set() 160 161 def run(self, doc): 162 start_level, force_id = self._get_meta() 163 slugify = self.config['slugify'] 164 sep = self.config['separator'] 165 for elem in doc.getiterator(): 166 if elem.tag in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: 167 if force_id: 168 if "id" in elem.attrib: 169 id = elem.get('id') 170 else: 171 id = slugify(''.join(itertext(elem)), sep) 172 elem.set('id', unique(id, self.IDs)) 173 if start_level: 174 level = int(elem.tag[-1]) + start_level 175 if level > 6: 176 level = 6 177 elem.tag = 'h%d' % level 178 179 180 def _get_meta(self): 181 """ Return meta data suported by this ext as a tuple """ 182 level = int(self.config['level']) - 1 183 force = self._str2bool(self.config['forceid']) 184 if hasattr(self.md, 'Meta'): 185 if 'header_level' in self.md.Meta: 186 level = int(self.md.Meta['header_level'][0]) - 1 187 if 'header_forceid' in self.md.Meta: 188 force = self._str2bool(self.md.Meta['header_forceid'][0]) 189 return level, force 190 191 def _str2bool(self, s, default=False): 192 """ Convert a string to a booleen value. """ 193 s = str(s) 194 if s.lower() in ['0', 'f', 'false', 'off', 'no', 'n']: 195 return False 196 elif s.lower() in ['1', 't', 'true', 'on', 'yes', 'y']: 197 return True 198 return default 199 200 201 class HeaderIdExtension(Extension): 202 def __init__(self, configs): 203 # set defaults 204 self.config = { 205 'level' : ['1', 'Base level for headers.'], 206 'forceid' : ['True', 'Force all headers to have an id.'], 207 'separator' : ['-', 'Word separator.'], 208 'slugify' : [slugify, 'Callable to generate anchors'], 209 } 210 211 for key, value in configs: 212 self.setConfig(key, value) 213 214 def extendMarkdown(self, md, md_globals): 215 md.registerExtension(self) 216 self.processor = HeaderIdTreeprocessor() 217 self.processor.md = md 218 self.processor.config = self.getConfigs() 219 if 'attr_list' in md.treeprocessors.keys(): 220 # insert after attr_list treeprocessor 221 md.treeprocessors.add('headerid', self.processor, '>attr_list') 222 else: 223 # insert after 'prettify' treeprocessor. 224 md.treeprocessors.add('headerid', self.processor, '>prettify') 225 226 def reset(self): 227 self.processor.IDs = set() 228 229 230 def makeExtension(configs=None): 231 return HeaderIdExtension(configs=configs) 232
