From 5cbb0417733afb88343e86efc686f099c970230b Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Sat, 3 Feb 2024 22:10:20 +0100 Subject: [PATCH] Update docs --- docs/dev-guide/themes.md | 9 +++++++-- mkdocs/structure/pages.py | 28 ++++++++++++++++++++-------- 2 files changed, 27 insertions(+), 10 deletions(-) diff --git a/docs/dev-guide/themes.md b/docs/dev-guide/themes.md index ea4b9911..35950522 100644 --- a/docs/dev-guide/themes.md +++ b/docs/dev-guide/themes.md @@ -86,7 +86,7 @@ The simplest `main.html` file is the following: - {% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }} + {{ page.content_title }} - {{ config.site_name }} {%- for path in config.extra_css %} {%- endfor %} @@ -354,6 +354,11 @@ All `page` objects contain the following attributes: show_root_full_path: false heading_level: 5 +::: mkdocs.structure.pages.Page.content_title + options: + show_root_full_path: false + heading_level: 5 + ::: mkdocs.structure.pages.Page.content options: show_root_full_path: false @@ -453,7 +458,7 @@ object to alter the behavior. For example, to display a different title on the homepage: ```django -{% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }} +{% if not page.is_homepage %}{{ page.content_title }} - {% endif %}{{ site_name }}<title> ``` ::: mkdocs.structure.pages.Page.previous_page diff --git a/mkdocs/structure/pages.py b/mkdocs/structure/pages.py index e14301a3..41ee1694 100644 --- a/mkdocs/structure/pages.py +++ b/mkdocs/structure/pages.py @@ -225,14 +225,15 @@ class Page(StructureItem): @weak_property def title(self) -> str | None: # type: ignore[override] """ - Returns the title for the current page. + Returns the title for the page, in the context of the nav. Before calling `read_source()`, this value is empty. It can also be updated by `render()`. - Check these in order and use the first that returns a valid title: - - value provided on init (passed in from config) + Checks these in order and uses the first that returns a valid title: + + - value specified in the `nav` config in mkdocs.yml (or the value that was passed when creating the `Page` programmatically) - value of metadata 'title' - - content of the first H1 in Markdown content + - content of the first H1 heading in Markdown content - convert filename to title """ if self.markdown is None: @@ -253,16 +254,27 @@ class Page(StructureItem): @property def content_title(self) -> str: """ + Returns the title for the page, in the context of the current page's content. + + NEW: **New in MkDocs 1.6.** + Similar to `title` but prioritizes the title from the document itself over the title specified in the `nav` config. - Raises if called before `render()` was called. + For themes, this should be preferred within the `<title>` tag. To apply the preferred behavior but keep compatibility with older versions, you can use: + + ```jinja + <title>{{ page.content_title or page.title }} + ``` + + Checks these in order and uses the first that returns a valid title: - Check these in order and use the first that returns a valid title: - value of metadata 'title' - - content of the first H1 in Markdown content - - value provided on init (passed in from config) + - content of the first H1 heading in Markdown content + - value specified in the `nav` config in mkdocs.yml (or the value that was passed when creating the `Page` programmatically) - convert filename to title + + When using this property outside of themes, do not access it before `render()` was called on the content, or it will raise. """ if self.content is None: raise RuntimeError("`content` field hasn't been set (via `render`)")