PageRenderTime 48ms CodeModel.GetById 18ms RepoModel.GetById 1ms app.codeStats 0ms

/markdown/extensions/toc.py

https://gitlab.com/Haritiana/Python-Markdown
Python | 310 lines | 264 code | 20 blank | 26 comment | 23 complexity | 84b900f671cdc70879c52d73ff1c0888 MD5 | raw file
  1. """
  2. Table of Contents Extension for Python-Markdown
  3. ===============================================
  4. See <https://pythonhosted.org/Markdown/extensions/toc.html>
  5. for documentation.
  6. Oringinal code Copyright 2008 [Jack Miller](http://codezen.org)
  7. All changes Copyright 2008-2014 The Python Markdown Project
  8. License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
  9. """
  10. from __future__ import absolute_import
  11. from __future__ import unicode_literals
  12. from . import Extension
  13. from ..treeprocessors import Treeprocessor
  14. from ..util import etree, parseBoolValue, AMP_SUBSTITUTE, HTML_PLACEHOLDER_RE, string_type
  15. import re
  16. import unicodedata
  17. def slugify(value, separator):
  18. """ Slugify a string, to make it URL friendly. """
  19. value = unicodedata.normalize('NFKD', value).encode('ascii', 'ignore')
  20. value = re.sub('[^\w\s-]', '', value.decode('ascii')).strip().lower()
  21. return re.sub('[%s\s]+' % separator, separator, value)
  22. IDCOUNT_RE = re.compile(r'^(.*)_([0-9]+)$')
  23. def unique(id, ids):
  24. """ Ensure id is unique in set of ids. Append '_1', '_2'... if not """
  25. while id in ids or not id:
  26. m = IDCOUNT_RE.match(id)
  27. if m:
  28. id = '%s_%d' % (m.group(1), int(m.group(2))+1)
  29. else:
  30. id = '%s_%d' % (id, 1)
  31. ids.add(id)
  32. return id
  33. def stashedHTML2text(text, md):
  34. """ Extract raw HTML from stash, reduce to plain text and swap with placeholder. """
  35. def _html_sub(m):
  36. """ Substitute raw html with plain text. """
  37. try:
  38. raw, safe = md.htmlStash.rawHtmlBlocks[int(m.group(1))]
  39. except (IndexError, TypeError): # pragma: no cover
  40. return m.group(0)
  41. if md.safeMode and not safe: # pragma: no cover
  42. return ''
  43. # Strip out tags and entities - leaveing text
  44. return re.sub(r'(<[^>]+>)|(&[\#a-zA-Z0-9]+;)', '', raw)
  45. return HTML_PLACEHOLDER_RE.sub(_html_sub, text)
  46. def nest_toc_tokens(toc_list):
  47. """Given an unsorted list with errors and skips, return a nested one.
  48. [{'level': 1}, {'level': 2}]
  49. =>
  50. [{'level': 1, 'children': [{'level': 2, 'children': []}]}]
  51. A wrong list is also converted:
  52. [{'level': 2}, {'level': 1}]
  53. =>
  54. [{'level': 2, 'children': []}, {'level': 1, 'children': []}]
  55. """
  56. ordered_list = []
  57. if len(toc_list):
  58. # Initialize everything by processing the first entry
  59. last = toc_list.pop(0)
  60. last['children'] = []
  61. levels = [last['level']]
  62. ordered_list.append(last)
  63. parents = []
  64. # Walk the rest nesting the entries properly
  65. while toc_list:
  66. t = toc_list.pop(0)
  67. current_level = t['level']
  68. t['children'] = []
  69. # Reduce depth if current level < last item's level
  70. if current_level < levels[-1]:
  71. # Pop last level since we know we are less than it
  72. levels.pop()
  73. # Pop parents and levels we are less than or equal to
  74. to_pop = 0
  75. for p in reversed(parents):
  76. if current_level <= p['level']:
  77. to_pop += 1
  78. else: # pragma: no cover
  79. break
  80. if to_pop:
  81. levels = levels[:-to_pop]
  82. parents = parents[:-to_pop]
  83. # Note current level as last
  84. levels.append(current_level)
  85. # Level is the same, so append to
  86. # the current parent (if available)
  87. if current_level == levels[-1]:
  88. (parents[-1]['children'] if parents
  89. else ordered_list).append(t)
  90. # Current level is > last item's level,
  91. # So make last item a parent and append current as child
  92. else:
  93. last['children'].append(t)
  94. parents.append(last)
  95. levels.append(current_level)
  96. last = t
  97. return ordered_list
  98. class TocTreeprocessor(Treeprocessor):
  99. def __init__(self, md, config):
  100. super(TocTreeprocessor, self).__init__(md)
  101. self.marker = config["marker"]
  102. self.title = config["title"]
  103. self.base_level = int(config["baselevel"]) - 1
  104. self.slugify = config["slugify"]
  105. self.sep = config["separator"]
  106. self.use_anchors = parseBoolValue(config["anchorlink"])
  107. self.use_permalinks = parseBoolValue(config["permalink"], False)
  108. if self.use_permalinks is None:
  109. self.use_permalinks = config["permalink"]
  110. self.header_rgx = re.compile("[Hh][123456]")
  111. def iterparent(self, root):
  112. ''' Iterator wrapper to get parent and child all at once. '''
  113. for parent in root.iter():
  114. for child in parent:
  115. yield parent, child
  116. def replace_marker(self, root, elem):
  117. ''' Replace marker with elem. '''
  118. for (p, c) in self.iterparent(root):
  119. text = ''.join(c.itertext()).strip()
  120. if not text:
  121. continue
  122. # To keep the output from screwing up the
  123. # validation by putting a <div> inside of a <p>
  124. # we actually replace the <p> in its entirety.
  125. # We do not allow the marker inside a header as that
  126. # would causes an enless loop of placing a new TOC
  127. # inside previously generated TOC.
  128. if c.text and c.text.strip() == self.marker and \
  129. not self.header_rgx.match(c.tag) and c.tag not in ['pre', 'code']:
  130. for i in range(len(p)):
  131. if p[i] == c:
  132. p[i] = elem
  133. break
  134. def set_level(self, elem):
  135. ''' Adjust header level according to base level. '''
  136. level = int(elem.tag[-1]) + self.base_level
  137. if level > 6:
  138. level = 6
  139. elem.tag = 'h%d' % level
  140. def add_anchor(self, c, elem_id): # @ReservedAssignment
  141. anchor = etree.Element("a")
  142. anchor.text = c.text
  143. anchor.attrib["href"] = "#" + elem_id
  144. anchor.attrib["class"] = "toclink"
  145. c.text = ""
  146. for elem in c:
  147. anchor.append(elem)
  148. while c:
  149. c.remove(c[0])
  150. c.append(anchor)
  151. def add_permalink(self, c, elem_id):
  152. permalink = etree.Element("a")
  153. permalink.text = ("%spara;" % AMP_SUBSTITUTE
  154. if self.use_permalinks is True
  155. else self.use_permalinks)
  156. permalink.attrib["href"] = "#" + elem_id
  157. permalink.attrib["class"] = "headerlink"
  158. permalink.attrib["title"] = "Permanent link"
  159. c.append(permalink)
  160. def build_toc_div(self, toc_list):
  161. """ Return a string div given a toc list. """
  162. div = etree.Element("div")
  163. div.attrib["class"] = "toc"
  164. # Add title to the div
  165. if self.title:
  166. header = etree.SubElement(div, "span")
  167. header.attrib["class"] = "toctitle"
  168. header.text = self.title
  169. def build_etree_ul(toc_list, parent):
  170. ul = etree.SubElement(parent, "ul")
  171. for item in toc_list:
  172. # List item link, to be inserted into the toc div
  173. li = etree.SubElement(ul, "li")
  174. link = etree.SubElement(li, "a")
  175. link.text = item.get('name', '')
  176. link.attrib["href"] = '#' + item.get('id', '')
  177. if item['children']:
  178. build_etree_ul(item['children'], li)
  179. return ul
  180. build_etree_ul(toc_list, div)
  181. prettify = self.markdown.treeprocessors.get('prettify')
  182. if prettify:
  183. prettify.run(div)
  184. return div
  185. def run(self, doc):
  186. # Get a list of id attributes
  187. used_ids = set()
  188. for el in doc.iter():
  189. if "id" in el.attrib:
  190. used_ids.add(el.attrib["id"])
  191. toc_tokens = []
  192. for el in doc.iter():
  193. if isinstance(el.tag, string_type) and self.header_rgx.match(el.tag):
  194. self.set_level(el)
  195. text = ''.join(el.itertext()).strip()
  196. # Do not override pre-existing ids
  197. if "id" not in el.attrib:
  198. innertext = stashedHTML2text(text, self.markdown)
  199. el.attrib["id"] = unique(self.slugify(innertext, self.sep), used_ids)
  200. toc_tokens.append({
  201. 'level': int(el.tag[-1]),
  202. 'id': el.attrib["id"],
  203. 'name': text
  204. })
  205. if self.use_anchors:
  206. self.add_anchor(el, el.attrib["id"])
  207. if self.use_permalinks:
  208. self.add_permalink(el, el.attrib["id"])
  209. div = self.build_toc_div(nest_toc_tokens(toc_tokens))
  210. if self.marker:
  211. self.replace_marker(doc, div)
  212. # serialize and attach to markdown instance.
  213. toc = self.markdown.serializer(div)
  214. for pp in self.markdown.postprocessors.values():
  215. toc = pp.run(toc)
  216. self.markdown.toc = toc
  217. class TocExtension(Extension):
  218. TreeProcessorClass = TocTreeprocessor
  219. def __init__(self, *args, **kwargs):
  220. self.config = {
  221. "marker": ['[TOC]',
  222. 'Text to find and replace with Table of Contents - '
  223. 'Set to an empty string to disable. Defaults to "[TOC]"'],
  224. "title": ["",
  225. "Title to insert into TOC <div> - "
  226. "Defaults to an empty string"],
  227. "anchorlink": [False,
  228. "True if header should be a self link - "
  229. "Defaults to False"],
  230. "permalink": [0,
  231. "True or link text if a Sphinx-style permalink should "
  232. "be added - Defaults to False"],
  233. "baselevel": ['1', 'Base level for headers.'],
  234. "slugify": [slugify,
  235. "Function to generate anchors based on header text - "
  236. "Defaults to the headerid ext's slugify function."],
  237. 'separator': ['-', 'Word separator. Defaults to "-".']
  238. }
  239. super(TocExtension, self).__init__(*args, **kwargs)
  240. def extendMarkdown(self, md, md_globals):
  241. md.registerExtension(self)
  242. self.md = md
  243. self.reset()
  244. tocext = self.TreeProcessorClass(md, self.getConfigs())
  245. # Headerid ext is set to '>prettify'. With this set to '_end',
  246. # it should always come after headerid ext (and honor ids assinged
  247. # by the header id extension) if both are used. Same goes for
  248. # attr_list extension. This must come last because we don't want
  249. # to redefine ids after toc is created. But we do want toc prettified.
  250. md.treeprocessors.add("toc", tocext, "_end")
  251. def reset(self):
  252. self.md.toc = ''
  253. def makeExtension(*args, **kwargs):
  254. return TocExtension(*args, **kwargs)