diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 26b95644..e0967ca2 100644 --- a/docs/about/release-notes.md +++ b/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,64 @@ 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 + +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 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 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 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. + +The global variable `favicon` maps to the configuration setting `site_favicon`. +Both the template variable and the configuration setting are being deprecated +and will issue a warning but continue to work for version 0.16, and may be +removed in a future version. Use `{{ base_url }}/img/favicon.ico` in your +template instead. Users can simply save a copy of their custom favicon icon to +`img/favicon.ico` in either their `docs_dir` or `theme_dir`. + +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 | +| favicon | {{ base_url }}/img/favicon.ico | + #### Increased Template Customization. (#607) The built-in themes have been updated by having each of their many parts wrapped @@ -110,8 +164,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 @@ -148,7 +202,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/index.md b/docs/index.md index d96dc1f5..919007c2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -245,6 +245,15 @@ Save your changes, and you'll see the ReadTheDocs theme being used. ![Screenshot](img/readthedocs.png) +## Changing the Favicon Icon + +By default, MkDocs uses the [MkDocs favicon] icon. To use a different icon, create +an `img` subdirectory in your `docs_dir` and copy your custom `favicon.ico` file +to that directory. MkDocs will automaticaly detect and use that file as your +favicon icon. + +[MkDocs favicon]: /img/favicon.ico + ## Building the site That's looking good. You're ready to deploy the first pass of your `MkLorum` diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 4f10c306..27f019ed 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -101,17 +101,6 @@ header. **default**: `null` -### site_favicon - -Set the favicon to use. Putting a `favicon.ico` into the `docs/` directory, the -config would look as follows: - -```yaml -site_favicon: favicon.ico -``` - -**default**: `null` - ### copyright Set the copyright information to be included in the documentation by the theme. diff --git a/docs/user-guide/custom-themes.md b/docs/user-guide/custom-themes.md index 8e045ae7..893b0def 100644 --- a/docs/user-guide/custom-themes.md +++ b/docs/user-guide/custom-themes.md @@ -72,7 +72,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 @@ -82,9 +82,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 @@ -106,42 +106,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] | -include_nav | [include_nav] | -include_next_prev | [include_next_prev] | -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 -[include_nav]: ./configuration.md#include_nav -[include_next_prev]: ./configuration.md#include_next_prev -[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 @@ -150,28 +130,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. @@ -183,9 +167,21 @@ folder on all pages you would do this: ``` -#### homepage_url +#### extra_css -Provides a relative path to the documentation homepage. +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 @@ -270,8 +266,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 @@ -383,7 +379,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 2dc3d3ca..ad06674c 100644 --- a/mkdocs/commands/build.py +++ b/mkdocs/commands/build.py @@ -66,15 +66,6 @@ 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 +75,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'], + 'favicon': config['site_favicon'], + + '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'] } @@ -269,25 +257,38 @@ 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)', + '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', + 'favicon': '{{ base_url }}/img/favicon.ico', + } 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) diff --git a/mkdocs/config/config_options.py b/mkdocs/config/config_options.py index 78ea5455..3e7e2073 100644 --- a/mkdocs/config/config_options.py +++ b/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: diff --git a/mkdocs/config/defaults.py b/mkdocs/config/defaults.py index a5ff9d77..db74caa6 100644 --- a/mkdocs/config/defaults.py +++ b/mkdocs/config/defaults.py @@ -33,7 +33,8 @@ DEFAULT_SCHEMA = ( ('site_author', config_options.Type(utils.string_types)), # The path to the favicon for a site - ('site_favicon', config_options.Type(utils.string_types)), + # TODO: remove this in version 1.0 + ('site_favicon', config_options.Deprecated()), # The MkDocs theme for the documentation. ('theme', config_options.Theme(default='mkdocs')), @@ -92,6 +93,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()), diff --git a/mkdocs/nav.py b/mkdocs/nav.py index f18441d3..c005e41e 100644 --- a/mkdocs/nav.py +++ b/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. 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/tests/integration/complicated_config/mkdocs.yml b/mkdocs/tests/integration/complicated_config/mkdocs.yml index b42f736a..ddfc71e4 100644 --- a/mkdocs/tests/integration/complicated_config/mkdocs.yml +++ b/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: diff --git a/mkdocs/themes/mkdocs/base.html b/mkdocs/themes/mkdocs/base.html index d99e7434..4846a895 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 %} + {% if config.site_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 @@