centersl/mkdocs
1
0
Fork 0
mirror of https://github.com/mkdocs/mkdocs.git synced 2026-03-27 09:58:31 +07:00
Code Issues Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Oleh Prypin
2024-02-03 22:10:20 +01:00
parent 5651524918
commit 5cbb041773
2 changed files with 27 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/dev-guide/themes.md
View File

@@ -86,7 +86,7 @@ The simplest `main.html` file is the following:
<!DOCTYPE html>
<html>
<head>
<title>{% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }}</title>
<title>{{ page.content_title }} - {{ config.site_name }}</title>
{%- for path in config.extra_css %}
<link href="{{ path | url }}" rel="stylesheet">
{%- 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 }}
<title>{% if not page.is_homepage %}{{ page.content_title }} - {% endif %}{{ site_name }}<title>
```
::: mkdocs.structure.pages.Page.previous_page

28
mkdocs/structure/pages.py
View File

@@ -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 }}</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`)")