Deprecate include_nav and include_next_previous.

Fixes #679 and #681.

docs/about/release-notes.md

@@ -27,19 +27,15 @@ The current and past members of the MkDocs team.
 
 #### Template variables refactored. (#874)
 
+##### Page Context
+
 Page specific variable names in the template context have been refactored as
 defined in [Custom Themes](../user-guide/custom-themes/#page). The
 old variable names will issue a warning but continue to work for version 0.16,
 but may be removed in a future version.
 
-No global variables were altered except `page_description`. Previously
-its value was altered programicaly based on whether the current
-page was the homepage. Now it simply maps to `config['site_description']`.
-Use `page.is_homepage` in the template to conditionally change the
-description.
-
-Any of the following old variables should be updated to the new ones in user
-created and third-party templates:
+Any of the following old page variables should be updated to the new ones in
+user created and third-party templates:
 
 | Old Variable Name | New Variable Name   |
 | ----------------- | ------------------- |
@@ -61,6 +57,26 @@ created and third-party templates:
 [page.previous_page]: ../user-guide/custom-themes/#pageprevious_page
 [page.next_page]: ../user-guide/custom-themes/#pagenext_page
 
+##### Global Context
+
+Additionaly, a number of global variables have been altered and/or deprecated
+and user created and third-party templates should be updated as outlined below:
+
+Previously, the global variable `include_nav` was altered programicaly based on
+the number of pages in the nav. The variable will issue a warning but continue
+to work for version 0.16, but may be removed in a future version. Use
+`{% if nav|length>1 %}` instead.
+
+Previously, the global variable `include_next_prev` was altered programicaly
+based on the number of pages in the nav. The variable will issue a warning but
+continue to work for version 0.16, but may be removed in a future version. Use
+`{% if page.next_page or page.previous_page %}` instead.
+
+Previously the global variable `page_description` was altered programicaly
+based on whether the current page was the homepage. Now it simply maps to
+`config['site_description']`. Use `{% if page.is_homepage %}` in the template to
+conditionally change the description.
+
 #### Increased Template Customization. (#607)
 
 The built-in themes have been updated by having each of their many parts wrapped

docs/user-guide/custom-themes.md

@@ -122,8 +122,6 @@ site_url          | [site_url]            |
 extra_css         | [extra_css]           |
 extra_javascript  | [extra_javascript]    |
 extra             | [extra]               |
-include_nav       | [include_nav]         |
-include_next_prev | [include_next_prev]   |
 copyright         | [copyright]           |
 google_analytics  | [google_analytics]    |
 
@@ -137,8 +135,6 @@ google_analytics  | [google_analytics]    |
 [extra_css]: ./configuration.md#extra_css
 [extra_javascript]: ./configuration.md#extra_javascript
 [extra]: ./configuration.md#extra
-[include_nav]: ./configuration.md#include_nav
-[include_next_prev]: ./configuration.md#include_next_prev
 [copyright]: ./configuration.md#copyright
 [google_analytics]: ./configuration.md#google_analytics
 

mkdocs/commands/build.py

@@ -269,25 +269,28 @@ def build_pages(config, dump_json=False, dirty=False):
 
     # TODO: remove DeprecationContext in v1.0 when all deprecated vars have been removed
     from jinja2.runtime import Context
-    deprecated_vars = [
-        'page_title',
-        'content',
-        'toc',
-        'meta',
-        'current_page',
-        'canonical_url',
-        'previous_page',
-        'next_page'
-    ]
+    deprecated_vars = {
+        'page_title': 'page.title',
+        'content': 'page.content',
+        'toc': 'page.toc',
+        'meta': 'page.meta',
+        'current_page': 'page.current_page',
+        'canonical_url': 'page.canonical_url',
+        'previous_page': 'page.previous_page',
+        'next_page': 'page.next_page',
+        'current_page': 'page',
+        'include_nav': 'nav|length>1',
+        'include_next_prev': "(page.next_page or page.previous_page)"
+    }
 
     class DeprecationContext(Context):
         def resolve(self, key):
-            """ Log a warning when acessing any deprecated variable name. """
+            """ Log a warning when accessing any deprecated variable name. """
             if key in deprecated_vars:
-                replacement = "page" if key == 'current_page' else "page.{0}".format(key)
                 log.warn(
-                    "Template variable warning: '{0}' is being deprecated and will not be "
-                    "available in a future version. Use '{1}' instead.".format(key, replacement)
+                    "Template variable warning: '{0}' is being deprecated "
+                    "and will not be available in a future version. Use "
+                    "'{1}' instead.".format(key, deprecated_vars[key])
                 )
             return super(DeprecationContext, self).resolve(key)
 

mkdocs/config/config_options.py

@@ -468,6 +468,16 @@ class NumPages(OptionallyRequired):
         super(NumPages, self).__init__(**kwargs)
         self.at_lest = at_lest
 
+    def pre_validation(self, config, key_name):
+        # TODO: delete deprecated `NumPages` class in version 1.0
+        # Numpages is only used by `include_nav` and `include_next_prev`,
+        # which are both deprecated, so we can delete the entire Option type.
+        if config.get(key_name) is not None:
+            # Only issue warning if option is defined by user.
+            warning = ('The configuration option {0} has been deprecated and will '
+                       'be removed in a future release of MkDocs.').format(key_name)
+            self.warnings.append(warning)
+
     def post_validation(self, config, key_name):
 
         if config[key_name] is not None:

mkdocs/config/defaults.py

@@ -92,6 +92,7 @@ DEFAULT_SCHEMA = (
     # Jinja2 and the global context.
     ('extra_templates', config_options.Extras()),
 
+    # TODO: delete deprecated `include_nav` and `include_next_previous` in version 1.0
     # Determine if the site should include the nav and next/prev elements.
     # Default, True if the site has more than one page, False otherwise.
     ('include_nav', config_options.NumPages()),

mkdocs/nav.py

@@ -41,6 +41,9 @@ class SiteNavigation(object):
     def __iter__(self):
         return iter(self.nav_items)
 
+    def __len__(self):
+        return len(self.nav_items)
+
     def walk_pages(self):
         """
         Returns each page in the site in turn.

mkdocs/tests/integration/complicated_config/mkdocs.yml

@@ -31,8 +31,6 @@ extra_javascript: ["tweak.js", ]
 
 extra_templates: ["custom.html", ]
 
-include_nav: true
-include_next_prev: false
 
 markdown_extensions:
     - toc:

mkdocs/themes/mkdocs/nav.html

@@ -3,7 +3,7 @@
 
         <!-- Collapsed navigation -->
         <div class="navbar-header">
-            {%- if include_nav or include_next_prev or repo_url %}
+            {%- if nav|length>1 or (page and (page.next_page or page.previous_page)) or repo_url %}
             <!-- Expander button -->
             <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
                 <span class="sr-only">Toggle navigation</span>
@@ -21,7 +21,7 @@
         <!-- Expanded navigation -->
         <div class="navbar-collapse collapse">
           {%- block site_nav %}
-            {%- if include_nav %}
+            {%- if nav|length>1 %}
                 <!-- Main navigation -->
                 <ul class="nav navbar-nav">
                 {%- for nav_item in nav %}
@@ -54,7 +54,7 @@
               {%- endblock %}
 
               {%- block next_prev %}
-                {%- if include_next_prev and page %}
+                {%- if page and (page.next_page or page.previous_page) %}
                     <li {% if not page.previous_page %}class="disabled"{% endif %}>
                         <a rel="next" {% if page.previous_page %}href="{{ page.previous_page.url }}"{% endif %}>
                             <i class="fa fa-arrow-left"></i> Previous