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`)")