headerid.py 7.5 KB

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