Add a level attribute to AnchorLinks.

This relimplements mkdocs#1272 on the current code in master. Thanks to 
@funkyfuture for the original work on this.

Also removes some unused code after mkdocs#1504.

Closes mkdocs#1272.

docs/about/release-notes.md

@@ -191,6 +191,7 @@ authors should review how [search and themes] interact.
 
 ### Other Changes and Additions to Development Version
 
+* Add a level attribute to AnchorLinks (#1272).
 * Add MkDocs version check to gh-deploy script (#640).
 * Improve Markdown extension error messages. (#782).
 * Drop official support for Python 3.3 and set `tornado>=5.0` (#1427).

docs/user-guide/custom-themes.md

@@ -234,8 +234,16 @@ The rendered Markdown as HTML, this is the contents of the documentation.
 
 ##### page.toc
 
-An object representing the Table of contents for a page. Displaying the table
-of contents as a simple list can be achieved like this.
+An iterable object representing the Table of contents for a page. Each item in
+the `toc` is an `AnchorLink` which contains the following attributes:
+
+* `AnchorLink.title`: The text of the item.
+* `AnchorLink.url`: The hash fragment of a URL pointing to the item.
+* `AnchorLink.level`: The zero-based level of the item.
+* `AnchorLink.children`: An iterable of any child items.
+
+The following example would display the top two levels of the Table of Contents
+for a page.
 
 ```django
 <ul>

mkdocs/structure/toc.py

@@ -39,8 +39,8 @@ class AnchorLink(object):
     """
     A single entry in the table of contents.
     """
-    def __init__(self, title, url):
-        self.title, self.url = title, url
+    def __init__(self, title, url, level):
+        self.title, self.url, self.level = title, url, level
         self.children = []
 
     def __str__(self):
@@ -99,8 +99,7 @@ def _parse_html_table_of_contents(html):
     Returns a list of all the parent AnchorLink instances.
     """
     lines = html.splitlines()[2:-2]
-    parents = []
-    ret = []
+    ret, parents, level = [], [], 0
     for line in lines:
         parser = _TOCParser()
         parser.feed(line)
@@ -110,7 +109,7 @@ def _parse_html_table_of_contents(html):
             except KeyError:
                 continue
             title = parser.title
-            nav = AnchorLink(title, href)
+            nav = AnchorLink(title, href, level)
             # Add the item to its parent if required.  If it is a topmost
             # item then instead append it to our return value.
             if parents:
@@ -119,8 +118,10 @@ def _parse_html_table_of_contents(html):
                 ret.append(nav)
             # If this item has children, store it as the current parent
             if line.endswith('<ul>'):
+                level += 1
                 parents.append(nav)
         elif line.startswith('</ul>'):
+            level -= 1
             if parents:
                 parents.pop()
 

mkdocs/tests/structure/toc_tests.py

@@ -178,3 +178,21 @@ def test_skip_no_href(self):
         toc = get_toc(html)
         self.assertEqual(str(toc).strip(), expected)
         self.assertEqual(len(toc), 1)
+
+    def test_level(self):
+        md = dedent("""
+        # Heading 1
+        ## Heading 1.1
+        ### Heading 1.1.1
+        ### Heading 1.1.2
+        ## Heading 1.2
+        """)
+        toc = get_toc(get_markdown_toc(md))
+
+        def get_level_sequence(items):
+            for item in items:
+                yield item.level
+                for c in get_level_sequence(item.children):
+                    yield c
+
+        self.assertEqual(tuple(get_level_sequence(toc)), (0, 1, 2, 2, 1))