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