Add extra config to support global template vars

This change adds a new configuration option called `extra` which allows
uers to add an arbitrary set of data to the config that is passed to the
template context.

Fixes #144

docs/user-guide/configuration.md

@@ -163,6 +163,13 @@ Set a list of JavaScript files to be included by the theme.
 
 **default**: By default `extra_javascript` will contain a list of all the JavaScript files found within the `docs_dir`, if none are found it will be `[]` (an empty list).
 
+
+### extra
+
+A set of key value pairs, where the values can be any valid YAML construct, that will be passed to the template. This allows for great flexibility when creating custom themes.
+
+**default**: By default `extra` will be an empty key value mapping.
+
 ## Preview controls
 
 ### use_directory_urls

docs/user-guide/styling-your-docs.md

@@ -119,15 +119,11 @@ Article content from each page specified in `mkdocs.yml` is inserted using the `
 
 ### Template Variables
 
-Each template in a theme is built with a template context. These are the variables that are available to theme. The context varies depending on the template that is being built. At the moment templates are either built with
-the global context or with a page specific context. The global context is used
-for HTML pages that don't represent an individual Markdown document, for
-example a 404.html page or search.html.
-
+Each template in a theme is built with a template context. These are the variables that are available to themes. The context varies depending on the template that is being built. At the moment templates are either built with the global context or with a page specific context. The global context is used for HTML pages that don't represent an individual Markdown document, for example a 404.html page or search.html.
 
 #### Global Context
 
-The following variables in the context map directly the the configuration file.
+The following variables in the context map directly the the [configuration options](/user-guide/configuration/).
 
 Variable Name     | Configuration name
 ----------------- | ------------------- |
@@ -140,6 +136,7 @@ repo_name         | repo_name           |
 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           |
@@ -237,6 +234,34 @@ The page object for the previous  page. The isage is the same as for
 ##### next_page
 The page object for the next page.The isage is the same as for `current_page`.
 
+#### Extra Context
+
+Additional variables can be passed to the template with the [`extra`](/user-guide/configuration/#extra) configuration option. This is a set of key value pairs that can make custom templates far more flexible.
+
+For example, this could be used to include the project version of all pages and a list of links related to the project. This can be achieved with the following `extra` configuration:
+
+```yaml
+extra:
+    version: 0.13.0
+    links:
+        - https://github.com/mkdocs
+        - https://docs.readthedocs.org/en/latest/builds.html#mkdocs
+        - http://www.mkdocs.org/
+```
+
+And then displayed with this HTML in the custom theme.
+
+```html
+{{ extra.version }}
+
+{% if extra.links %}
+  <ul>
+  {% for link in extra.links %}
+      <li>{{ link }}</li>
+  {% endfor %}
+  </ul>
+{% endif %}
+```
 
 ### Search and themes
 

mkdocs/build.py

@@ -91,7 +91,9 @@ def get_global_context(nav, config):
         'google_analytics': config['google_analytics'],
 
         'mkdocs_version': mkdocs.__version__,
-        'build_date_utc': datetime.utcnow()
+        'build_date_utc': datetime.utcnow(),
+
+        'extra': config['extra']
     }
 
 

mkdocs/config/defaults.py

@@ -96,4 +96,11 @@ DEFAULT_SCHEMA = (
     # enabling strict mode causes MkDocs to stop the build when a problem is
     # encountered rather than display an error.
     ('strict', config_options.Type(bool, default=False)),
+
+    # extra is a mapping/dictionary of data that is passed to the template.
+    # This allows template authors to require extra configuration that not
+    # relevant to all themes and doesn't need to be explicitly supported by
+    # MkDocs itself. A good example here would be including the current
+    # project version.
+    ('extra', config_options.Type(dict, default={})),
 )

mkdocs/tests/build_tests.py

@@ -7,6 +7,7 @@ import tempfile
 import unittest
 
 from six.moves import zip
+import mock
 
 from mkdocs import build, nav
 from mkdocs.config import base as config_base, defaults as config_defaults
@@ -343,3 +344,22 @@ class BuildTests(unittest.TestCase):
         """)
 
         self.assertEqual(html.strip(), expected_html)
+
+    def test_extra_context(self):
+
+        # Same as the default schema, but don't verify the docs_dir exists.
+        config = config_base.Config(schema=config_defaults.DEFAULT_SCHEMA)
+        config.load_dict({
+            'site_name': "Site",
+            'extra': {
+                'a': 1
+            }
+        })
+
+        self.assertEqual(config.validate(), ([], []))
+
+        context = build.get_global_context(mock.Mock(), config)
+
+        self.assertEqual(context['extra'], {
+            'a': 1
+        })