third_party/markdown/extensions/headerid.py

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