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 |