diff options
| -rw-r--r-- | docs/extensions/header_id.md | 131 | ||||
| -rw-r--r-- | markdown/extensions/headerid.py | 97 | ||||
| -rw-r--r-- | mkdocs.yml | 1 | ||||
| -rw-r--r-- | tests/test_extensions.py | 54 |
4 files changed, 0 insertions, 283 deletions
diff --git a/docs/extensions/header_id.md b/docs/extensions/header_id.md deleted file mode 100644 index 82e8e2c..0000000 --- a/docs/extensions/header_id.md +++ /dev/null @@ -1,131 +0,0 @@ -title: HeaderId Extension - -HeaderId -======== - -Summary -------- - -The HeaderId extension automatically generates `id` attributes for the header -elements (`h1`-`h6`) in the resulting HTML document. - -This extension is included in the standard Markdown library. - -!!! warning - This extension is **Pending Deprecation**. The [Table of Contents][toc] - Extension should be used instead, which offers most the features of this - extension and more. - -[toc]: toc.md - -Syntax ------- - -By default, all headers will automatically have unique `id` attributes -generated based upon the text of the header (see below to turn this off). -Note this example, in which all three headers would have the same `id`: - -```md -#Header -#Header -#Header -``` - -Results in: - -```html -<h1 id="header">Header</h1> -<h1 id="header_1">Header</h1> -<h1 id="header_2">Header</h1> -``` - -Usage ------ - -See [Extensions](index.md) for general extension usage, specify -`markdown.extensions.headerid` as the name of the extension. - -See the [Library Reference](../reference.md#extensions) for information about -configuring extensions. - -The following options are provided to configure the output: - -* **`level`**: Base level for headers. - - Default: `1` - - The `level` setting allows you to automatically adjust the header levels to - fit within the hierarchy of your HTML templates. For example, suppose the - markdown text for a page should not contain any headers higher than level 3 - (`<h3>`). The following will accomplish that: - - :::pycon - >>> text = ''' - ... #Some Header - ... ## Next Level''' - >>> from markdown.extensions.headerid import HeaderIdExtension - >>> html = markdown.markdown(text, extensions=[HeaderIdExtension(level=3)]) - >>> print html - <h3 id="some_header">Some Header</h3> - <h4 id="next_level">Next Level</h4>' - -* **`forceid`**: Force all headers to have an id. - - Default: `True` - - The `forceid` setting turns on or off the automatically generated ids for - headers that do not have one explicitly defined (using the - [Attribute List](attr_list.md) extension). - - :::pycon - >>> text = ''' - ... # Some Header - ... # Header with ID # { #foo }''' - >>> html = markdown.markdown(text, - extensions=['markdown.extensions.attr_list', - HeaderIdExtension(forceid=False)]) - >>> print html - <h1>Some Header</h1> - <h1 id="foo">Header with ID</h1> - -* **`separator`**: Word separator. Character which replaces white space in id. - - Default: `-` - -* **`slugify`**: Callable to generate anchors. - - Default: `markdown.extensions.headerid.slugify` - - If you would like to use a different algorithm to define the ids, you can - pass in a callable which takes two arguments: - - * `value`: The string to slugify. - * `separator`: The Word Separator. - -Using with Meta-Data --------------------- - -The HeaderId extension also supports the [Meta-Data](meta_data.md) extension. -Please see the documentation for that extension for specifics. The supported -meta-data keywords are: - -* `header_level` -* `header_forceid` - -When used, the meta-data will override the settings provided through the -`extension_configs` interface. - -This document: - -```md -header_level: 2 -header_forceid: Off - -# A Header -``` - -Will result in the following output: - -```html -<h2>A Header</h2> -``` diff --git a/markdown/extensions/headerid.py b/markdown/extensions/headerid.py deleted file mode 100644 index fdcc8f2..0000000 --- a/markdown/extensions/headerid.py +++ /dev/null @@ -1,97 +0,0 @@ -""" -HeaderID Extension for Python-Markdown -====================================== - -Auto-generate id attributes for HTML headers. - -See <https://Python-Markdown.github.io/extensions/header_id> -for documentation. - -Original code Copyright 2007-2011 [Waylan Limberg](http://achinghead.com/). - -All changes Copyright 2011-2014 The Python Markdown Project - -License: [BSD](http://www.opensource.org/licenses/bsd-license.php) - -""" - -from __future__ import absolute_import -from __future__ import unicode_literals -from . import Extension -from ..treeprocessors import Treeprocessor -from ..util import parseBoolValue -from .toc import slugify, unique, stashedHTML2text -import warnings - - -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: - if elem.tag in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']: - if force_id: - if "id" in elem.attrib: - id = elem.get('id') - else: - id = stashedHTML2text(''.join(elem.itertext()), self.md) - id = slugify(id, 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 = parseBoolValue(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 = parseBoolValue(self.md.Meta['header_forceid'][0]) - return level, force - - -class HeaderIdExtension(Extension): - def __init__(self, *args, **kwargs): - # 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'] - } - - super(HeaderIdExtension, self).__init__(*args, **kwargs) - - warnings.warn( - 'The HeaderId Extension is pending deprecation. Use the TOC Extension instead.', - PendingDeprecationWarning - ) - - 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(*args, **kwargs): - return HeaderIdExtension(*args, **kwargs) @@ -27,7 +27,6 @@ pages: - Extra: extensions/extra.md - Fenced Code Blocks: extensions/fenced_code_blocks.md - Footnotes: extensions/footnotes.md - - HeaderId: extensions/header_id.md - Meta-Data: extensions/meta_data.md - New Line to Break: extensions/nl2br.md - Sane Lists: extensions/sane_lists.md diff --git a/tests/test_extensions.py b/tests/test_extensions.py index 37b6fd6..5dee0fd 100644 --- a/tests/test_extensions.py +++ b/tests/test_extensions.py @@ -388,60 +388,6 @@ line 3 self.assertTrue('<code class="language-python">' in md.convert(text)) -class TestHeaderId(unittest.TestCase): - """ Test HeaderId Extension. """ - - def setUp(self): - self.md = markdown.Markdown(extensions=['markdown.extensions.headerid']) - - def testBasicHeaderId(self): - """ Test Basic HeaderID """ - - text = "# Some Header #" - self.assertEqual( - self.md.convert(text), - '<h1 id="some-header">Some Header</h1>' - ) - - def testNoAutoIds(self): - """ Test HeaderIDs with no auto generated IDs. """ - - text = '# Some Header\n# Another Header' - self.assertEqual( - markdown.markdown(text, extensions=[markdown.extensions.headerid.HeaderIdExtension(forceid=False)]), - '<h1>Some Header</h1>\n' - '<h1>Another Header</h1>' - ) - - def testHeaderIdWithMetaData(self): - """ Test Header IDs with MetaData extension. """ - - text = '''header_level: 2 -header_forceid: Off - -# A Header''' - self.assertEqual( - markdown.markdown(text, extensions=['markdown.extensions.headerid', 'markdown.extensions.meta']), - '<h2>A Header</h2>' - ) - - def testHeaderIdWithAttr_List(self): - """ Test HeaderIDs with Attr_List extension. """ - - text = '# Header1 {: #foo }\n# Header2 {: .bar }' - self.assertEqual( - markdown.markdown(text, extensions=['markdown.extensions.headerid', 'markdown.extensions.attr_list']), - '<h1 id="foo">Header1</h1>\n' - '<h1 class="bar" id="header2">Header2</h1>' - ) - # Switch order extensions are loaded - should be no change in behavior. - self.assertEqual( - markdown.markdown(text, extensions=['markdown.extensions.attr_list', 'markdown.extensions.headerid']), - '<h1 id="foo">Header1</h1>\n' - '<h1 class="bar" id="header2">Header2</h1>' - ) - - class TestMetaData(unittest.TestCase): """ Test MetaData extension. """ |