Refactor global template variables.

Any template variables which mirrored a config setting have been deprecated and should be accessed via the coresponding config template variable. This resolves the rest of #874.
2026-03-27 09:58:31 +07:00 · 2016-08-15 16:11:41 -04:00
parent 4a532be1f0
commit 2641b6409d
10 changed files with 162 additions and 122 deletions
--- a/docs/about/release-notes.md
+++ b/docs/about/release-notes.md
@@ -59,24 +59,54 @@ user created and third-party templates:

 ##### Global Context

-Additionaly, a number of global variables have been altered and/or deprecated
+Additionally, 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
+Previously, the global variable `include_nav` was altered programmatically 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
+Previously, the global variable `include_next_prev` was altered programmatically
 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
+Previously the global variable `page_description` was altered programmatically
 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.

+The global variable `homepage_url` maps directly to `nav.homepage.url` and is
+being deprecated. The variable will issue a warning but continue to work for
+version 0.16, but may be removed in a future version. Use `nav.homepage.url`
+instead.
+
+A number of variables map directly to similarly named variables in the `config`.
+Those variables are being deprecated and will issue a warning but continue to
+work for version 0.16, but may be removed in a future version. Use
+`config.var_name` instead, where `var_name` is the name of one of the
+[configuration] variables.
+
+[configuration]: /user-guide/configuration.md
+
+Below is a summary of all of the changes made to the global context:
+
+| Old Variable Name | New Variable Name or Expression        |
+| ----------------- | -------------------------------------- |
+| current_page      | page                                   |
+| include_nav       | nav&#124;length&gt;1                   |
+| include_next_prev | (page.next_page or page.previous_page) |
+| site_name         | config.site_name                       |
+| site_author       | config.site_author                     |
+| page_description  | config.site_description                |
+| repo_url          | config.repo_url                        |
+| repo_name         | config.repo_name                       |
+| site_url          | config.site_url                        |
+| copyright         | config.copyright                       |
+| google_analytics  | config.google_analytics                |
+| homepage_url      | nav.homepage.url                       |
+
 #### Increased Template Customization. (#607)

 The built-in themes have been updated by having each of their many parts wrapped
@@ -126,8 +156,8 @@ the `extra_css` or `extra_javascript` config settings going forward.

 For large sites the build time required to create the pages can become problematic,
 thus a "dirty" build mode was created. This mode simply compares the modified time
-of the generated html and source markdown. If the markdown has changed since the
-html then the page is re-constructed. Otherwise, the page remains as is. This mode
+of the generated HTML and source markdown. If the markdown has changed since the
+HTML then the page is re-constructed. Otherwise, the page remains as is. This mode
 may be invoked in both the `mkdocs serve` and `mkdocs build` commands:

 ```text
@@ -164,7 +194,7 @@ better conform with the documented [layout].
 * Fixed issues with Unicode file names under Windows and Python 2. (#833)
 * Improved the styling of in-line code in the MkDocs theme. (#718)
 * Bugfix: convert variables to JSON when being passed to JavaScript (#850)
-* Updated the ReadTheDocs theme to match the upstream font sizes and colours
+* Updated the ReadTheDocs theme to match the upstream font sizes and colors
  more closely. (#857)
 * Fixes an issue with permalink markers showing when the mouse was far above
  them (#843)
--- a/docs/user-guide/custom-themes.md
+++ b/docs/user-guide/custom-themes.md
@@ -73,7 +73,7 @@ The simplest `main.html` file is the following:
 ```

 Article content from each page specified in `mkdocs.yml` is inserted using the
-`{{ content }}` tag. Stylesheets and scripts can be brought into this theme as
+`{{ content }}` tag. Style-sheets and scripts can be brought into this theme as
 with a normal HTML file. Navbars and tables of contents can also be generated
 and included automatically, through the `nav` and `toc` objects, respectively.
 If you wish to write your own theme, it is recommended to start with one of
@@ -83,9 +83,9 @@ the [built-in themes] and modify it accordingly.

    As MkDocs uses [Jinja] as its template engine, you have access to all the
    power of Jinja, including [template inheritance]. You may notice that the
-    themes included with MkDocs make extensive use of template inheritance anf
+    themes included with MkDocs make extensive use of template inheritance and
    blocks, allowing users to easily override small bits and pieces of the
-    templates from the [theme_dir]. Therefore, the builtin themes are
+    templates from the [theme_dir]. Therefore, the built-in themes are
    implemented in a `base.html` file, which `main.html` extends. Although not
    required, third party template authors are encouraged to follow a similar
    pattern and may want to define the same [blocks] as are used in the built-in
@@ -107,38 +107,22 @@ example a 404.html page or search.html.

 ### Global Context

-The following variables in the context map directly the [configuration options
-](/user-guide/configuration.md).
+The following variables are available globally on any template.

-Variable Name     | Configuration name
----------------- | ------------------- |
-site_name         | [site_name]           |
-site_author       | [site_author]         |
-favicon           | [site_favicon]        |
-page_description  | [site_description]    |
-repo_url          | [repo_url]            |
-repo_name         | [repo_name]           |
-site_url          | [site_url]            |
-extra_css         | [extra_css]           |
-extra_javascript  | [extra_javascript]    |
-extra             | [extra]               |
-copyright         | [copyright]           |
-google_analytics  | [google_analytics]    |
+#### config

-[site_name]: ./configuration.md#site_name
-[site_author]: ./configuration.md#site_author
-[site_favicon]: ./configuration.md#site_favicon
-[site_description]: ./configuration.md#site_description
-[repo_url]: ./configuration.md#repo_url
-[repo_name]: ./configuration.md#repo_name
-[site_url]: ./configuration.md#site_url
-[extra_css]: ./configuration.md#extra_css
-[extra_javascript]: ./configuration.md#extra_javascript
-[extra]: ./configuration.md#extra
-[copyright]: ./configuration.md#copyright
-[google_analytics]: ./configuration.md#google_analytics
+The `config` variable is an instance of MkDocs' config object generated from the
+`mkdocs.yml` config file. While you can use any config option, some commonly
+used options include:

-The following variables provide information about the navigation and location.
+* [config.site_name](./configuration.md#site_name)
+* [config.site_url](./configuration.md#site_url)
+* [config.site_author](./configuration.md#site_author)
+* [config.site_description](./configuration.md#site_description)
+* [config.repo_url](./configuration.md#repo_url)
+* [config.repo_name](./configuration.md#repo_name)
+* [config.copyright](./configuration.md#copyright)
+* [config.google_analytics](./configuration.md#google_analytics)

 #### nav

@@ -147,28 +131,32 @@ Following is a basic usage example which outputs the first and second level
 navigation as a nested list.

 ```django
-<ul>
-  {% for nav_item in nav %}
-      {% if nav_item.children %}
-          <li>{{ nav_item.title }}
-              <ul>
-              {% for nav_item in nav_item.children %}
-                  <li class="{% if nav_item.active%}current{%endif%}">
-                      <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
-                  </li>
-              {% endfor %}
-              </ul>
-          </li>
-      {% else %}
-          <li class="{% if nav_item.active%}current{%endif%}">
-              <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
-          </li>
-      {% endif %}
-
-  {% endfor %}
-</ul>
+{% if nav|length>1 %}
+    <ul>
+    {% for nav_item in nav %}
+        {% if nav_item.children %}
+            <li>{{ nav_item.title }}
+                <ul>
+                {% for nav_item in nav_item.children %}
+                    <li class="{% if nav_item.active%}current{%endif%}">
+                        <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+                    </li>
+                {% endfor %}
+                </ul>
+            </li>
+        {% else %}
+            <li class="{% if nav_item.active%}current{%endif%}">
+                <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+            </li>
+        {% endif %}
+    {% endfor %}
+    </ul>
+{% endif %}
 ```

+The `nav` object also contains a `hompage` object, which points to the `page`
+object of the homepage. For example, you may want to access `nav.homepage.url`.
+
 #### base_url

 The `base_url` provides a relative path to the root of the MkDocs project.
@@ -180,9 +168,29 @@ folder on all pages you would do this:
 <script src="{{ base_url }}/js/theme.js"></script>
 ```

-#### homepage_url
+#### favicon

-Provides a relative path to the documentation homepage.
+Contains the URL to the icon defined in the [site_favicon] config settings.
+Unlike the config setting, which contains a local path, this variable contains
+an absolute path from the homepage.
+
+[site_favicon]: configuration.md#site_favicon
+
+#### extra_css
+
+Contains a list of URLs to the style-sheets listed in the [extra_css]
+config setting. Unlike the config setting, which contains local paths, this
+variable contains absolute paths from the homepage.
+
+[extra_css]: configuration.md#extra_css
+
+#### extra_javascript
+
+Contains a list of URLs to the scripts listed in the [extra_javascript] config
+setting. Unlike the config setting, which contains local paths, this variable
+contains absolute paths from the homepage.
+
+[extra_javascript]: configuration.md#extra_javascript

 #### mkdocs_version

@@ -267,8 +275,8 @@ The URL to the current page not including the `site_url` from the configuration.
 ##### page.is_homepage

 Evaluates to `True` for the homepage of the site and `False` for all other
-pages. This can be used in conjuction with other attributes of the `page`
-object to alter the behavior. For example, to display a differant title
+pages. This can be used in conjunction with other attributes of the `page`
+object to alter the behavior. For example, to display a different title
 on the homepage:

 ```django
@@ -380,7 +388,7 @@ Bootswatch theme].

 !!! Note

-    It is not strictly nessecary to package a theme, as the entire theme
+    It is not strictly necessary to package a theme, as the entire theme
    can be contained in the `theme_dir`. If you have created a "one-off theme,"
    that should be sufficent. However, if you intend to distribute your theme
    for others to use, packaging the theme has some advantages. By packaging
--- a/mkdocs/commands/build.py
+++ b/mkdocs/commands/build.py
@@ -66,15 +66,11 @@ def get_global_context(nav, config):
    to app pages.
    """

-    site_name = config['site_name']
-
    if config['site_favicon']:
        site_favicon = nav.url_context.make_relative('/' + config['site_favicon'])
    else:
        site_favicon = None

-    page_description = config['site_description']
-
    extra_javascript = utils.create_media_urls(nav, config['extra_javascript'])

    extra_css = utils.create_media_urls(nav, config['extra_css'])
@@ -84,36 +80,33 @@ def get_global_context(nav, config):
    timestamp = int(os.environ.get('SOURCE_DATE_EPOCH', timegm(datetime.utcnow().utctimetuple())))

    return {
-        'site_name': site_name,
-        'site_author': config['site_author'],
        'favicon': site_favicon,
-        'page_description': page_description,
-
-        # Note that there's intentionally repetition here. Rather than simply
-        # provide the config dictionary we instead pass everything explicitly.
-        #
-        # This helps ensure that we can throughly document the context that
-        # gets passed to themes.
-        'repo_url': config['repo_url'],
-        'repo_name': config['repo_name'],
        'nav': nav,
        'base_url': nav.url_context.make_relative('/'),
-        'homepage_url': nav.homepage.url,
-        'site_url': config['site_url'],

        'extra_css': extra_css,
        'extra_javascript': extra_javascript,

+        'mkdocs_version': mkdocs.__version__,
+        'build_date_utc': datetime.utcfromtimestamp(timestamp),
+
+        'config': config,
+
+        # TODO: remove the rest in 1.0 as they are deprecated
+        'site_name': config['site_name'],
+        'site_url': config['site_url'],
+        'site_author': config['site_author'],
+        'homepage_url': nav.homepage.url,
+        'page_description': config['site_description'],
+
+        'repo_url': config['repo_url'],
+        'repo_name': config['repo_name'],
+
        'include_nav': config['include_nav'],
        'include_next_prev': config['include_next_prev'],

        'copyright': config['copyright'],
-        'google_analytics': config['google_analytics'],
-
-        'mkdocs_version': mkdocs.__version__,
-        'build_date_utc': datetime.utcfromtimestamp(timestamp),
-
-        'config': config
+        'google_analytics': config['google_analytics']
    }


@@ -280,7 +273,16 @@ def build_pages(config, dump_json=False, dirty=False):
        'next_page': 'page.next_page',
        'current_page': 'page',
        'include_nav': 'nav|length>1',
-        'include_next_prev': "(page.next_page or page.previous_page)"
+        'include_next_prev': '(page.next_page or page.previous_page)',
+        'site_name': 'config.site_name',
+        'site_author': 'config.site_author',
+        'page_description': 'config.site_description',
+        'repo_url': 'config.repo_url',
+        'repo_name': 'config.repo_name',
+        'site_url': 'config.site_url',
+        'copyright': 'config.copyright',
+        'google_analytics': 'config.google_analytics',
+        'homepage_url': 'nav.homepage.url',
    }

    class DeprecationContext(Context):
--- a/mkdocs/templates/sitemap.xml
+++ b/mkdocs/templates/sitemap.xml
@@ -4,14 +4,14 @@
    {% if nav_item.children %}
        {% for nav_item in nav_item.children %}
    <url>
-     <loc>{{ site_url }}{{ nav_item.abs_url }}</loc>
+     <loc>{{ config.site_url }}{{ nav_item.abs_url }}</loc>
     <lastmod>{{nav_item.update_date}}</lastmod>
     <changefreq>daily</changefreq>
    </url>
        {% endfor %}
    {% else %}
    <url>
-     <loc>{{ site_url }}{{ nav_item.abs_url }}</loc>
+     <loc>{{ config.site_url }}{{ nav_item.abs_url }}</loc>
     <lastmod>{{nav_item.update_date}}</lastmod>
     <changefreq>daily</changefreq>
    </url>
--- a/mkdocs/themes/mkdocs/base.html
+++ b/mkdocs/themes/mkdocs/base.html
@@ -6,14 +6,14 @@
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        {% if page and page.is_homepage %}<meta name="description" content="{{ config['site_description'] }}">{% endif %}
-        {% if site_author %}<meta name="author" content="{{ site_author }}">{% endif %}
+        {% if config.site_author %}<meta name="author" content="{{ config.site_author }}">{% endif %}
        {% if page and page.canonical_url %}<link rel="canonical" href="{{ page.canonical_url }}">{% endif %}
        {% if favicon %}<link rel="shortcut icon" href="{{ base_url }}/{{ favicon }}">
        {% else %}<link rel="shortcut icon" href="{{ base_url }}/img/favicon.ico">{% endif %}
      {%- endblock %}

      {%- block htmltitle %}
-        <title>{% if page and page.title and not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }}</title>
+        <title>{% if page and page.title and not page.is_homepage %}{{ page.title }} - {% endif %}{{ config.site_name }}</title>
      {%- endblock %}

      {%- block styles %}
@@ -39,14 +39,14 @@
      {%- endblock %}

      {%- block analytics %}
-        {%- if google_analytics %}
+        {%- if config.google_analytics %}
        <script>
            (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
            (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
            m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
            })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

-            ga('create', '{{ google_analytics[0] }}', '{{ google_analytics[1] }}');
+            ga('create', '{{ config.google_analytics[0] }}', '{{ config.google_analytics[1] }}');
            ga('send', 'pageview');
        </script>
        {%- endif %}
@@ -69,8 +69,8 @@
        <footer class="col-md-12">
          {%- block footer %}
            <hr>
-            {%- if copyright %}
-                <p>{{ copyright }}</p>
+            {%- if config.copyright %}
+                <p>{{ config.copyright }}</p>
            {%- endif %}
            <p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</p>
          {%- endblock %}
--- a/mkdocs/themes/mkdocs/nav.html
+++ b/mkdocs/themes/mkdocs/nav.html
@@ -3,7 +3,7 @@

        <!-- Collapsed navigation -->
        <div class="navbar-header">
-            {%- if nav|length>1 or (page and (page.next_page or page.previous_page)) or repo_url %}
+            {%- if nav|length>1 or (page and (page.next_page or page.previous_page)) or config.repo_url %}
            <!-- Expander button -->
            <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
                <span class="sr-only">Toggle navigation</span>
@@ -14,7 +14,7 @@
            {%- endif %}

          {%- block site_name %}
-            <a class="navbar-brand" href="{{ homepage_url }}">{{ site_name }}</a>
+            <a class="navbar-brand" href="{{ nav.homepage.url }}">{{ config.site_name }}</a>
          {%- endblock %}
        </div>

@@ -69,15 +69,15 @@
              {%- endblock %}

              {%- block repo %}
-                {%- if repo_url %}
+                {%- if config.repo_url %}
                    <li>
-                        <a href="{{ repo_url }}">
-                            {%- if repo_name == 'GitHub' %}
+                        <a href="{{ config.repo_url }}">
+                            {%- if config.repo_name == 'GitHub' %}
                                <i class="fa fa-github"></i>
-                            {%- elif repo_name == 'Bitbucket' -%}
+                            {%- elif config.repo_name == 'Bitbucket' -%}
                                <i class="fa fa-bitbucket"></i>
                            {%- endif -%}
-                            {{ repo_name }}
+                            {{ config.repo_name }}
                        </a>
                    </li>
                {%- endif %}
--- a/mkdocs/themes/readthedocs/base.html
+++ b/mkdocs/themes/readthedocs/base.html
@@ -6,14 +6,14 @@
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  {% if page and page.is_homepage %}<meta name="description" content="{{ page_description }}">{% endif %}
-  {% if site_author %}<meta name="author" content="{{ site_author }}">{% endif %}
+  {% if page and page.is_homepage %}<meta name="description" content="{{ config.site_description }}">{% endif %}
+  {% if config.site_author %}<meta name="author" content="{{ config.site_author }}">{% endif %}
  {% if favicon %}<link rel="shortcut icon" href="{{ favicon }}">
  {% else %}<link rel="shortcut icon" href="{{ base_url }}/img/favicon.ico">{% endif %}
  {%- endblock %}

  {%- block htmltitle %}
-  <title>{% if page and page.title and not page.is_hompage %}{{ page.title }} - {% endif %}{{ site_name }}</title>
+  <title>{% if page and page.title and not page.is_hompage %}{{ page.title }} - {% endif %}{{ config.site_name }}</title>
  {%- endblock %}
  
  {%- block styles %}
@@ -44,14 +44,14 @@
  {%- block extrahead %} {% endblock %}

  {%- block analytics %}
-  {% if google_analytics %}
+  {% if config.google_analytics %}
  <script>
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

-      ga('create', '{{ google_analytics[0] }}', '{{ google_analytics[1] }}');
+      ga('create', '{{ config.google_analytics[0] }}', '{{ config.google_analytics[1] }}');
      ga('send', 'pageview');
  </script>
  {% endif %}
@@ -66,7 +66,7 @@
    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
      <div class="wy-side-nav-search">
 	{%- block site_name %}
-        <a href="{{ homepage_url }}" class="icon icon-home"> {{ site_name }}</a>
+        <a href="{{ nav.homepage.url }}" class="icon icon-home"> {{ config.site_name }}</a>
 	{%- endblock %}
 	{%- block search_button %}
        {% include "searchbox.html" %}
@@ -90,7 +90,7 @@
      {# MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #}
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
-        <a href="{{ homepage_url }}">{{ site_name }}</a>
+        <a href="{{ nav.homepage.url }}">{{ config.site_name }}</a>
      </nav>

      {# PAGE CONTENT #}
--- a/mkdocs/themes/readthedocs/breadcrumbs.html
+++ b/mkdocs/themes/readthedocs/breadcrumbs.html
@@ -1,6 +1,6 @@
 <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
-    <li><a href="{{ homepage_url }}">Docs</a> &raquo;</li>
+    <li><a href="{{ nav.homepage.url }}">Docs</a> &raquo;</li>
    {% if page %}
      {% for doc in page.ancestors %}
        {% if doc.link %}
@@ -15,11 +15,11 @@
      {%- block repo %}
      {% if page and page.edit_url %}
        <a href="{{ page.edit_url }}"
-        {%- if repo_name|lower == 'github' %}
+        {%- if config.repo_name|lower == 'github' %}
          class="icon icon-github"
-        {%- elif repo_name|lower == 'bitbucket' %}
+        {%- elif config.repo_name|lower == 'bitbucket' %}
          class="icon icon-bitbucket"
-        {% endif %}> Edit on {{ repo_name }}</a>
+        {% endif %}> Edit on {{ config.repo_name }}</a>
      {% endif %}
      {%- endblock %}
    </li>
--- a/mkdocs/themes/readthedocs/footer.html
+++ b/mkdocs/themes/readthedocs/footer.html
@@ -16,8 +16,8 @@

  <div role="contentinfo">
    <!-- Copyright etc -->
-    {% if copyright %}
-      <p>{{ copyright }}</p>
+    {% if config.copyright %}
+      <p>{{ config.copyright }}</p>
    {% endif %}
  </div>

--- a/mkdocs/themes/readthedocs/versions.html
+++ b/mkdocs/themes/readthedocs/versions.html
@@ -1,9 +1,9 @@
 <div class="rst-versions" role="note" style="cursor: pointer">
    <span class="rst-current-version" data-toggle="rst-current-version">
-      {% if repo_name == 'GitHub' %}
-          <a href="{{ repo_url }}" class="icon icon-github" style="float: left; color: #fcfcfc"> GitHub</a>
-      {% elif repo_name == 'Bitbucket' %}
-          <a href="{{ repo_url }}" class="icon icon-bitbucket" style="float: left; color: #fcfcfc"> BitBucket</a>
+      {% if config.repo_name == 'GitHub' %}
+          <a href="{{ config.repo_url }}" class="icon icon-github" style="float: left; color: #fcfcfc"> GitHub</a>
+      {% elif config.repo_name == 'Bitbucket' %}
+          <a href="{{ config.repo_url }}" class="icon icon-bitbucket" style="float: left; color: #fcfcfc"> BitBucket</a>
      {% endif %}
      {% if page.previous_page %}
        <span><a href="{{ page.previous_page.url }}" style="color: #fcfcfc;">&laquo; Previous</a></span>