From 2641b6409d3b9089b5f297565831b103d2fd0cd2 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Mon, 15 Aug 2016 16:11:41 -0400 Subject: [PATCH] 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. --- docs/about/release-notes.md | 48 ++++++-- docs/user-guide/custom-themes.md | 122 +++++++++++---------- mkdocs/commands/build.py | 50 +++++---- mkdocs/templates/sitemap.xml | 4 +- mkdocs/themes/mkdocs/base.html | 12 +- mkdocs/themes/mkdocs/nav.html | 14 +-- mkdocs/themes/readthedocs/base.html | 14 +-- mkdocs/themes/readthedocs/breadcrumbs.html | 8 +- mkdocs/themes/readthedocs/footer.html | 4 +- mkdocs/themes/readthedocs/versions.html | 8 +- 10 files changed, 162 insertions(+), 122 deletions(-) diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index c2331fc1..7f1f13b4 100644 --- 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|length>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) diff --git a/docs/user-guide/custom-themes.md b/docs/user-guide/custom-themes.md index f602f71c..2800de84 100644 --- 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 - +{% if nav|length>1 %} + +{% 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: ``` -#### 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 diff --git a/mkdocs/commands/build.py b/mkdocs/commands/build.py index e0ae9a2d..53a8d386 100644 --- 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): diff --git a/mkdocs/templates/sitemap.xml b/mkdocs/templates/sitemap.xml index bffe7dbe..68ad7725 100644 --- 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 %} - {{ site_url }}{{ nav_item.abs_url }} + {{ config.site_url }}{{ nav_item.abs_url }} {{nav_item.update_date}} daily {% endfor %} {% else %} - {{ site_url }}{{ nav_item.abs_url }} + {{ config.site_url }}{{ nav_item.abs_url }} {{nav_item.update_date}} daily diff --git a/mkdocs/themes/mkdocs/base.html b/mkdocs/themes/mkdocs/base.html index d99e7434..df6b421c 100644 --- a/mkdocs/themes/mkdocs/base.html +++ b/mkdocs/themes/mkdocs/base.html @@ -6,14 +6,14 @@ {% if page and page.is_homepage %}{% endif %} - {% if site_author %}{% endif %} + {% if config.site_author %}{% endif %} {% if page and page.canonical_url %}{% endif %} {% if favicon %} {% else %}{% endif %} {%- endblock %} {%- block htmltitle %} - {% if page and page.title and not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }} + {% if page and page.title and not page.is_homepage %}{{ page.title }} - {% endif %}{{ config.site_name }} {%- endblock %} {%- block styles %} @@ -39,14 +39,14 @@ {%- endblock %} {%- block analytics %} - {%- if google_analytics %} + {%- if config.google_analytics %} {%- endif %} @@ -69,8 +69,8 @@