toc.py 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253
  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. Table of Contents Extension for Python-Markdown
  33. * * *
  34. (c) 2008 [Jack Miller](http://codezen.org)
  35. Dependencies:
  36. * [Markdown 2.1+](http://packages.python.org/Markdown/)
  37. """
  38. from __future__ import absolute_import
  39. from __future__ import unicode_literals
  40. from . import Extension
  41. from ..treeprocessors import Treeprocessor
  42. from ..util import etree
  43. from .headerid import slugify, unique, itertext
  44. import re
  45. def order_toc_list(toc_list):
  46. """Given an unsorted list with errors and skips, return a nested one.
  47. [{'level': 1}, {'level': 2}]
  48. =>
  49. [{'level': 1, 'children': [{'level': 2, 'children': []}]}]
  50. A wrong list is also converted:
  51. [{'level': 2}, {'level': 1}]
  52. =>
  53. [{'level': 2, 'children': []}, {'level': 1, 'children': []}]
  54. """
  55. def build_correct(remaining_list, prev_elements=[{'level': 1000}]):
  56. if not remaining_list:
  57. return [], []
  58. current = remaining_list.pop(0)
  59. if not 'children' in current.keys():
  60. current['children'] = []
  61. if not prev_elements:
  62. # This happens for instance with [8, 1, 1], ie. when some
  63. # header level is outside a scope. We treat it as a
  64. # top-level
  65. next_elements, children = build_correct(remaining_list, [current])
  66. current['children'].append(children)
  67. return [current] + next_elements, []
  68. prev_element = prev_elements.pop()
  69. children = []
  70. next_elements = []
  71. # Is current part of the child list or next list?
  72. if current['level'] > prev_element['level']:
  73. #print "%d is a child of %d" % (current['level'], prev_element['level'])
  74. prev_elements.append(prev_element)
  75. prev_elements.append(current)
  76. prev_element['children'].append(current)
  77. next_elements2, children2 = build_correct(remaining_list, prev_elements)
  78. children += children2
  79. next_elements += next_elements2
  80. else:
  81. #print "%d is ancestor of %d" % (current['level'], prev_element['level'])
  82. if not prev_elements:
  83. #print "No previous elements, so appending to the next set"
  84. next_elements.append(current)
  85. prev_elements = [current]
  86. next_elements2, children2 = build_correct(remaining_list, prev_elements)
  87. current['children'].extend(children2)
  88. else:
  89. #print "Previous elements, comparing to those first"
  90. remaining_list.insert(0, current)
  91. next_elements2, children2 = build_correct(remaining_list, prev_elements)
  92. children.extend(children2)
  93. next_elements += next_elements2
  94. return next_elements, children
  95. ordered_list, __ = build_correct(toc_list)
  96. return ordered_list
  97. class TocTreeprocessor(Treeprocessor):
  98. # Iterator wrapper to get parent and child all at once
  99. def iterparent(self, root):
  100. for parent in root.getiterator():
  101. for child in parent:
  102. yield parent, child
  103. def add_anchor(self, c, elem_id): #@ReservedAssignment
  104. if self.use_anchors:
  105. anchor = etree.Element("a")
  106. anchor.text = c.text
  107. anchor.attrib["href"] = "#" + elem_id
  108. anchor.attrib["class"] = "toclink"
  109. c.text = ""
  110. for elem in c.getchildren():
  111. anchor.append(elem)
  112. c.remove(elem)
  113. c.append(anchor)
  114. def build_toc_etree(self, div, toc_list):
  115. # Add title to the div
  116. if self.config["title"]:
  117. header = etree.SubElement(div, "span")
  118. header.attrib["class"] = "toctitle"
  119. header.text = self.config["title"]
  120. def build_etree_ul(toc_list, parent):
  121. ul = etree.SubElement(parent, "ul")
  122. for item in toc_list:
  123. # List item link, to be inserted into the toc div
  124. li = etree.SubElement(ul, "li")
  125. link = etree.SubElement(li, "a")
  126. link.text = item.get('name', '')
  127. link.attrib["href"] = '#' + item.get('id', '')
  128. if item['children']:
  129. build_etree_ul(item['children'], li)
  130. return ul
  131. return build_etree_ul(toc_list, div)
  132. def run(self, doc):
  133. div = etree.Element("div")
  134. div.attrib["class"] = "toc"
  135. header_rgx = re.compile("[Hh][123456]")
  136. self.use_anchors = self.config["anchorlink"] in [1, '1', True, 'True', 'true']
  137. # Get a list of id attributes
  138. used_ids = set()
  139. for c in doc.getiterator():
  140. if "id" in c.attrib:
  141. used_ids.add(c.attrib["id"])
  142. toc_list = []
  143. marker_found = False
  144. for (p, c) in self.iterparent(doc):
  145. text = ''.join(itertext(c)).strip()
  146. if not text:
  147. continue
  148. # To keep the output from screwing up the
  149. # validation by putting a <div> inside of a <p>
  150. # we actually replace the <p> in its entirety.
  151. # We do not allow the marker inside a header as that
  152. # would causes an enless loop of placing a new TOC
  153. # inside previously generated TOC.
  154. if c.text and c.text.strip() == self.config["marker"] and \
  155. not header_rgx.match(c.tag) and c.tag not in ['pre', 'code']:
  156. for i in range(len(p)):
  157. if p[i] == c:
  158. p[i] = div
  159. break
  160. marker_found = True
  161. if header_rgx.match(c.tag):
  162. # Do not override pre-existing ids
  163. if not "id" in c.attrib:
  164. elem_id = unique(self.config["slugify"](text, '-'), used_ids)
  165. c.attrib["id"] = elem_id
  166. else:
  167. elem_id = c.attrib["id"]
  168. tag_level = int(c.tag[-1])
  169. toc_list.append({'level': tag_level,
  170. 'id': elem_id,
  171. 'name': text})
  172. self.add_anchor(c, elem_id)
  173. toc_list_nested = order_toc_list(toc_list)
  174. self.build_toc_etree(div, toc_list_nested)
  175. prettify = self.markdown.treeprocessors.get('prettify')
  176. if prettify: prettify.run(div)
  177. if not marker_found:
  178. # serialize and attach to markdown instance.
  179. toc = self.markdown.serializer(div)
  180. for pp in self.markdown.postprocessors.values():
  181. toc = pp.run(toc)
  182. self.markdown.toc = toc
  183. class TocExtension(Extension):
  184. TreeProcessorClass = TocTreeprocessor
  185. def __init__(self, configs=[]):
  186. self.config = { "marker" : ["[TOC]",
  187. "Text to find and replace with Table of Contents -"
  188. "Defaults to \"[TOC]\""],
  189. "slugify" : [slugify,
  190. "Function to generate anchors based on header text-"
  191. "Defaults to the headerid ext's slugify function."],
  192. "title" : [None,
  193. "Title to insert into TOC <div> - "
  194. "Defaults to None"],
  195. "anchorlink" : [0,
  196. "1 if header should be a self link"
  197. "Defaults to 0"]}
  198. for key, value in configs:
  199. self.setConfig(key, value)
  200. def extendMarkdown(self, md, md_globals):
  201. tocext = self.TreeProcessorClass(md)
  202. tocext.config = self.getConfigs()
  203. # Headerid ext is set to '>prettify'. With this set to '_end',
  204. # it should always come after headerid ext (and honor ids assinged
  205. # by the header id extension) if both are used. Same goes for
  206. # attr_list extension. This must come last because we don't want
  207. # to redefine ids after toc is created. But we do want toc prettified.
  208. md.treeprocessors.add("toc", tocext, "_end")
  209. def makeExtension(configs={}):
  210. return TocExtension(configs=configs)