| # markdown is released under the BSD license |
| # Copyright 2007, 2008 The Python Markdown Project (v. 1.7 and later) |
| # Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b) |
| # Copyright 2004 Manfred Stienstra (the original version) |
| # |
| # All rights reserved. |
| # |
| # Redistribution and use in source and binary forms, with or without |
| # modification, are permitted provided that the following conditions are met: |
| # |
| # * Redistributions of source code must retain the above copyright |
| # notice, this list of conditions and the following disclaimer. |
| # * Redistributions in binary form must reproduce the above copyright |
| # notice, this list of conditions and the following disclaimer in the |
| # documentation and/or other materials provided with the distribution. |
| # * Neither the name of the <organization> nor the |
| # names of its contributors may be used to endorse or promote products |
| # derived from this software without specific prior written permission. |
| # |
| # THIS SOFTWARE IS PROVIDED BY THE PYTHON MARKDOWN PROJECT ''AS IS'' AND ANY |
| # EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
| # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
| # DISCLAIMED. IN NO EVENT SHALL ANY CONTRIBUTORS TO THE PYTHON MARKDOWN PROJECT |
| # BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| # POSSIBILITY OF SUCH DAMAGE. |
| |
| |
| """ |
| HeaderID Extension for Python-Markdown |
| ====================================== |
| |
| Auto-generate id attributes for HTML headers. |
| |
| Basic usage: |
| |
| >>> import markdown |
| >>> text = "# Some Header #" |
| >>> md = markdown.markdown(text, ['headerid']) |
| >>> print md |
| <h1 id="some-header">Some Header</h1> |
| |
| All header IDs are unique: |
| |
| >>> text = ''' |
| ... #Header |
| ... #Header |
| ... #Header''' |
| >>> md = markdown.markdown(text, ['headerid']) |
| >>> print md |
| <h1 id="header">Header</h1> |
| <h1 id="header_1">Header</h1> |
| <h1 id="header_2">Header</h1> |
| |
| To fit within a html template's hierarchy, set the header base level: |
| |
| >>> text = ''' |
| ... #Some Header |
| ... ## Next Level''' |
| >>> md = markdown.markdown(text, ['headerid(level=3)']) |
| >>> print md |
| <h3 id="some-header">Some Header</h3> |
| <h4 id="next-level">Next Level</h4> |
| |
| Works with inline markup. |
| |
| >>> text = '#Some *Header* with [markup](http://example.com).' |
| >>> md = markdown.markdown(text, ['headerid']) |
| >>> print md |
| <h1 id="some-header-with-markup">Some <em>Header</em> with <a href="http://example.com">markup</a>.</h1> |
| |
| Turn off auto generated IDs: |
| |
| >>> text = ''' |
| ... # Some Header |
| ... # Another Header''' |
| >>> md = markdown.markdown(text, ['headerid(forceid=False)']) |
| >>> print md |
| <h1>Some Header</h1> |
| <h1>Another Header</h1> |
| |
| Use with MetaData extension: |
| |
| >>> text = '''header_level: 2 |
| ... header_forceid: Off |
| ... |
| ... # A Header''' |
| >>> md = markdown.markdown(text, ['headerid', 'meta']) |
| >>> print md |
| <h2>A Header</h2> |
| |
| Copyright 2007-2011 [Waylan Limberg](http://achinghead.com/). |
| |
| Project website: <http://packages.python.org/Markdown/extensions/header_id.html> |
| Contact: markdown@freewisdom.org |
| |
| License: BSD (see ../docs/LICENSE for details) |
| |
| Dependencies: |
| * [Python 2.3+](http://python.org) |
| * [Markdown 2.0+](http://packages.python.org/Markdown/) |
| |
| """ |
| |
| from __future__ import absolute_import |
| from __future__ import unicode_literals |
| from . import Extension |
| from ..treeprocessors import Treeprocessor |
| import re |
| import logging |
| import unicodedata |
| |
| logger = logging.getLogger('MARKDOWN') |
| |
| IDCOUNT_RE = re.compile(r'^(.*)_([0-9]+)$') |
| |
| |
| def slugify(value, separator): |
| """ Slugify a string, to make it URL friendly. """ |
| value = unicodedata.normalize('NFKD', value).encode('ascii', 'ignore') |
| value = re.sub('[^\w\s-]', '', value.decode('ascii')).strip().lower() |
| return re.sub('[%s\s]+' % separator, separator, value) |
| |
| |
| def unique(id, ids): |
| """ Ensure id is unique in set of ids. Append '_1', '_2'... if not """ |
| while id in ids or not id: |
| m = IDCOUNT_RE.match(id) |
| if m: |
| id = '%s_%d'% (m.group(1), int(m.group(2))+1) |
| else: |
| id = '%s_%d'% (id, 1) |
| ids.add(id) |
| return id |
| |
| |
| def itertext(elem): |
| """ Loop through all children and return text only. |
| |
| Reimplements method of same name added to ElementTree in Python 2.7 |
| |
| """ |
| if elem.text: |
| yield elem.text |
| for e in elem: |
| for s in itertext(e): |
| yield s |
| if e.tail: |
| yield e.tail |
| |
| |
| class HeaderIdTreeprocessor(Treeprocessor): |
| """ Assign IDs to headers. """ |
| |
| IDs = set() |
| |
| def run(self, doc): |
| start_level, force_id = self._get_meta() |
| slugify = self.config['slugify'] |
| sep = self.config['separator'] |
| for elem in doc.getiterator(): |
| if elem.tag in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: |
| if force_id: |
| if "id" in elem.attrib: |
| id = elem.get('id') |
| else: |
| id = slugify(''.join(itertext(elem)), sep) |
| elem.set('id', unique(id, self.IDs)) |
| if start_level: |
| level = int(elem.tag[-1]) + start_level |
| if level > 6: |
| level = 6 |
| elem.tag = 'h%d' % level |
| |
| |
| def _get_meta(self): |
| """ Return meta data suported by this ext as a tuple """ |
| level = int(self.config['level']) - 1 |
| force = self._str2bool(self.config['forceid']) |
| if hasattr(self.md, 'Meta'): |
| if 'header_level' in self.md.Meta: |
| level = int(self.md.Meta['header_level'][0]) - 1 |
| if 'header_forceid' in self.md.Meta: |
| force = self._str2bool(self.md.Meta['header_forceid'][0]) |
| return level, force |
| |
| def _str2bool(self, s, default=False): |
| """ Convert a string to a booleen value. """ |
| s = str(s) |
| if s.lower() in ['0', 'f', 'false', 'off', 'no', 'n']: |
| return False |
| elif s.lower() in ['1', 't', 'true', 'on', 'yes', 'y']: |
| return True |
| return default |
| |
| |
| class HeaderIdExtension(Extension): |
| def __init__(self, configs): |
| # set defaults |
| self.config = { |
| 'level' : ['1', 'Base level for headers.'], |
| 'forceid' : ['True', 'Force all headers to have an id.'], |
| 'separator' : ['-', 'Word separator.'], |
| 'slugify' : [slugify, 'Callable to generate anchors'], |
| } |
| |
| for key, value in configs: |
| self.setConfig(key, value) |
| |
| def extendMarkdown(self, md, md_globals): |
| md.registerExtension(self) |
| self.processor = HeaderIdTreeprocessor() |
| self.processor.md = md |
| self.processor.config = self.getConfigs() |
| if 'attr_list' in md.treeprocessors.keys(): |
| # insert after attr_list treeprocessor |
| md.treeprocessors.add('headerid', self.processor, '>attr_list') |
| else: |
| # insert after 'prettify' treeprocessor. |
| md.treeprocessors.add('headerid', self.processor, '>prettify') |
| |
| def reset(self): |
| self.processor.IDs = set() |
| |
| |
| def makeExtension(configs=None): |
| return HeaderIdExtension(configs=configs) |