From 7156c6d3983256d0aa7e9c34b9ce603116f9bf79 Mon Sep 17 00:00:00 2001
From: Waylan Limberg <waylan@gmail.com>
Date: Thu, 30 Jun 2011 12:23:38 -0400
Subject: Refactored HeaderId extension to no longer include defining ids. It
 only autogenerates ids. If you want to define your own, use the attr_list
 extension. Also expanded HeaderId extension to use the same algorithm as the
 TOC extension (which is better) for slugifying the header text. Added config
 settings to override the default word separator and the slugify callable.
 Closes #16 as the reported bug is for a removed feature.

---
 docs/extensions/HeaderId.txt | 95 ++++++++++++++++++++++----------------------
 docs/extensions/index.txt    |  3 +-
 2 files changed, 50 insertions(+), 48 deletions(-)

(limited to 'docs/extensions')

diff --git a/docs/extensions/HeaderId.txt b/docs/extensions/HeaderId.txt
index efd1eb8..b8382ba 100644
--- a/docs/extensions/HeaderId.txt
+++ b/docs/extensions/HeaderId.txt
@@ -4,86 +4,87 @@ HeaderId
 Summary
 -------
 
-An extension to Python-Markdown that adds an 'id' attribute to HTML header 
-elements (h1-h6) in markdown's output.
+An extension to Python-Markdown that automatically generates 'id' attributes
+for HTML header elements (h1-h6) in markdown's output.
 
 This extension is included in the standard Markdown library.
 
 Syntax
 ------
 
-The basic syntax follows [PHP Markdown Extra][]'s implementation:
-
-[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#header-id
-
-    Header 1            {#header1}
-    ========
-
-    ## Header 2 ##      {#header2}
-
-will result in the following HTML:
-
-    <h1 id="header1">Header 1</h1>
-
-    <h2 id="header2">Header 2</h2>
-
-However, there is much more that this extension does.
-
 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":
 
     #Header
-    #Another Header {#header}
+    #Header
     #Header
 
 Results in:
 
     <h1 id="header">Header</h1>
-    <h1 id="header_1">Another Header</h1>
-    <h1 id="header_2">Third Header</h1>
+    <h1 id="header_1">Header</h1>
+    <h1 id="header_2">Header</h1>
 
 Configuring the Output
 ----------------------
 
-The HeaderId extension has two configuration settings:
+The HeaderId extension has four configuration settings:
 
 * **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:
+
+        >>>  text = '''
+        ... #Some Header
+        ... ## Next Level'''
+        >>> html = markdown.markdown(text, extensions=['headerid(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 `level` setting allows you to automatically adjust the header levels to fit
-within the hierarchy of your html templates. For example, the markdown text for
-this page should not contain any headers higher than level 3 (`<h3>`). 
-Therefore, do the following:
-
-    >>>  text = '''
-    ... #Some Header
-    ... ## Next Level'''
-    >>> html = markdown.markdown(text, ['headerid(level=3)'])
-    >>> print html
-    <h3 id="some_header">Some Header</h3>
-    <h4 id="next_level">Next Level</h4>'
-
-The `forceid` setting turns on or off the automatically generated ids for 
-headers that do not have one explicitly defined.
-
-    >>> text = '''
-    ... # Some Header
-    ... # Header with ID # { #foo }'''
-    >>> html = markdown.markdown(text, ['headerid(forceid=False)'])
-    >>> print html
-    <h1>Some Header</h1>
-    <h1 id="foo">Header with ID</h1>
+    The `forceid` setting turns on or off the automatically generated ids for 
+    headers that do not have one explicitly defined (using the attr_list 
+    extension).
+
+        >>> text = '''
+        ... # Some Header
+        ... # Header with ID # { #foo }'''
+        >>> html = markdown.markdown(text, 
+                        extensions=['attr_list', 'headerid(forceid=False)'])
+        >>> print html
+        <h1>Some Header</h1>
+        <h1 id="foo">Header with ID</h1>
+
+* **separator**: Word separator. Character which replaces whitespace 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]] Extension. Please see the documentation for that extension for specifics. The supported meta-data keywords are:
+The HeaderId Extension also supports the [[Meta-Data]] Extension. Please see 
+the documentation for that extension for specifics. The supported meta-data 
+keywords are:
 
 * `header_level`
 * `header_forceid`
diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt
index 6f43519..d0726e6 100644
--- a/docs/extensions/index.txt
+++ b/docs/extensions/index.txt
@@ -15,11 +15,12 @@ available to you.
     * [[Definition_Lists]]
     * [[Fenced_Code_Blocks]]
     * [[Footnotes]]
-    * [[HeaderId]]
+    * [[Attr_List]]
     * [[Tables]]
 * [[attr_list]]
 * [[CodeHilite]]
 * [[HTML_Tidy]]
+* [[HeaderId]]
 * [[ImageLinks]]
 * [[Meta-Data]]
 * [[nl2br]]
-- 
cgit v1.2.3