Update release notes

docs/about/release-notes.md

@@ -27,7 +27,7 @@ The current and past members of the MkDocs team.
 * [@oprypin](https://github.com/oprypin/)
 * [@ultrabug](https://github.com/ultrabug/)
 
-## Version 1.6.0 (2024-04-??)
+## Version 1.6.0 (2024-04-18)
 
 ### Local preview
 
@@ -41,17 +41,25 @@ The current and past members of the MkDocs team.
 
 > DANGER: **Changed from version 1.5.**
 
-The `exclude_docs` config was renamed to the **new config `draft_docs`**. Please replace it in your config files if you wish to still use the "drafts" functionality. See [documentation](../user-guide/configuration.md#draft_docs).
+**The `exclude_docs` config was split up into two separate concepts.**
 
-The `exclude_docs` now instead *always* completely excludes the listed documents from the site.
+The `exclude_docs` config no longer has any special behavior for `mkdocs serve` - it now always completely excludes the listed documents from the site.
+
+If you wish to use the "drafts" functionality like the `exclude_docs` key used to do in MkDocs 1.5, please switch to the **new config key `draft_docs`**.
+
+See [documentation](../user-guide/configuration.md#exclude_docs).
+
+Other changes:
 
 * Reduce warning levels when a "draft" page has a link to a non-existent file. Context: #3449
 
 ### Update to deduction of page titles
 
-MkDocs 1.5 had a change in behavior in deducing the page titles. Unfortunately this could cause unescaped HTML tags or entities to appear in edge cases.
+MkDocs 1.5 had a change in behavior in deducing the page titles from the first heading. Unfortunately this could cause unescaped HTML tags or entities to appear in edge cases.
 
-It still remains the case that `Page.title` is expected to contain HTML entities and is passed directly to the themes, but tags are now fully sanitized.
+Now tags are always fully sanitized from the title. Though it still remains the case that [`Page.title`][mkdocs.structure.pages.Page.title] is expected to contain HTML entities and is passed directly to the themes.
+
+Images (notably, emojis in some extensions) get preserved in the title only through their `alt` attribute's value.
 
 Context: #3578
 
@@ -73,7 +81,7 @@ The "mkdocs" theme got a big update to a newer version of Bootstrap, meaning a s
 
 The "mkdocs" theme now has support for dark mode - both automatic (based on the OS/browser setting) and with a manual toggle. Both of these options are **not** enabled by default and need to be configured explicitly.
 
-See `color_mode`, `user_color_mode_toggle` in [**documentation**](../user-guide/choosing-your-theme.md#mkdocs)
+See `color_mode`, `user_color_mode_toggle` in [**documentation**](../user-guide/choosing-your-theme.md#mkdocs).
 
 Context: #3493
 
@@ -93,7 +101,9 @@ See [**documentation**](../user-guide/configuration.md/#enabled-option). Context
 
 ##### Absolute links
 
-Historically, within Markdown, MkDocs only recognized **relative** links that lead to another physical `*.md` document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. Whereas absolute links were left unmodified (making them often not work as expected or, more recently, warned against). If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly.
+> Historically, within Markdown, MkDocs only recognized **relative** links that lead to another physical `*.md` document (or media file). This is a good convention to follow because then the source pages are also freely browsable without MkDocs, for example on GitHub. Whereas absolute links were left unmodified (making them often not work as expected or, more recently, warned against).
+
+If you dislike having to always use relative links, now you can opt into absolute links and have them work correctly.
 
 If you set the setting `validation.links.absolute_links` to the new value `relative_to_docs`, all Markdown links starting with `/` will be understood as being relative to the `docs_dir` root. The links will then be validated for correctness according to all the other rules that were already working for relative links in prior versions of MkDocs. For the HTML output, these links will still be turned relative so that the site still works reliably.
 
@@ -138,18 +148,16 @@ Plugins and extensions that insert anchors, in order to be compatible with this,
 
 If you as a user are dealing with falsely reported missing anchors and there's no way to resolve this, you can choose to disable these messages by setting this option to `ignore` (and they are at INFO level by default anyway).
 
-Context: #3463
+See [**documentation**](../user-guide/configuration.md#validation). Context: #3463
 
----
+Other changes:
 
-*   When the `nav` config is not specified at all, the `not_in_nav` setting (originally added in 1.5.0) gains an additional behavior: These documents will not be part of the automatically deduced navigation. Context: #3443
+*   When the `nav` config is not specified at all, the `not_in_nav` setting (originally added in 1.5.0) gains an additional behavior: documents covered by `not_in_nav` will not be part of the automatically deduced navigation. Context: #3443
 
-*   Fix: the `!relative` YAML tag for `markdown_extensions` (originally added in 1.5.0) was broken in many typical use cases, now it should work correctly.
+*   Fix: the `!relative` YAML tag for `markdown_extensions` (originally added in 1.5.0) - it was broken in many typical use cases.
 
     See [**documentation**](../user-guide/configuration.md#paths-relative-to-the-current-file-or-site). Context: #3466
 
----
-
 *   Config validation now exits on first error, to avoid showing bizarre secondary errors. Context: #3437
 
 *   MkDocs used to shorten error messages for unexpected errors such as "file not found", but that is no longer the case, the full error message and stack trace will be possible to see (unless the error has a proper handler, of course). Context: #3445
@@ -158,23 +166,23 @@ Context: #3463
 
 #### Plugins can add multiple handlers for the same event type, at multiple priorities
 
-See `mkdocs.plugins.CombinedEvent` in [**documentation**](http://www.mkdocs.org/dev-guide/plugins/#event-priorities). Context: #3448
+See [`mkdocs.plugins.CombinedEvent`][] in [**documentation**](../dev-guide/plugins.md#event-priorities). Context: #3448
 
 #### Enabling true generated files and expanding the [`File`][mkdocs.structure.files.File] API
 
 See [**documentation**][mkdocs.structure.files.File].
 
-*   There is a new pair of attributes `File.content_string`/`content_bytes` that becomes the official API for obtaining the content of a file and is used by MkDocs itself.
+*   There is a new pair of attributes [`File.content_string`][mkdocs.structure.files.File.content_string]/[`content_bytes`][mkdocs.structure.files.File.content_bytes] that becomes the official API for obtaining the content of a file and is used by MkDocs itself.
 
-    This replaces the old approach where one had to manually read the file located at `File.abs_src_path`, although that is still the primary action that these new attributes do under the hood.
+    This replaces the old approach where one had to manually read the file located at [`File.abs_src_path`][mkdocs.structure.files.File.abs_src_path], although that is still the primary action that these new attributes do under the hood.
 
 *   The content of a `File` can be backed by a string and no longer has to be a real existing file at `abs_src_path`.
 
     It is possible to **set** the attribute `File.content_string` or `File.content_bytes` and it will take precedence over `abs_src_path`.
 
     Further, `abs_src_path` is no longer guaranteed to be present and can be `None` instead. MkDocs itself still uses physical files in all cases, but eventually plugins will appear that don't populate this attribute.
 
-*   There is a new constructor `File.generated()` that should be used by plugins instead of the `File()` constructor. It is much more convenient because one doesn't need to manually look up the values such as `docs_dir` and `use_directory_urls`. Its signature is one of:
+*   There is a new constructor [`File.generated()`][mkdocs.structure.files.File.generated] that should be used by plugins instead of the `File()` constructor. It is much more convenient because one doesn't need to manually look up the values such as `docs_dir` and `use_directory_urls`. Its signature is one of:
 
     ```python
     f = File.generated(config: MkDocsConfig, src_uri: str, content: str | bytes)
@@ -190,17 +198,17 @@ See [**documentation**][mkdocs.structure.files.File].
 
     For large content it is still best to use physical files, but one no longer needs to manipulate the path by providing a fake unused `docs_dir`.
 
-*   There is a new attribute `File.generated_by` that arose by convention - for generated files it should be set to the name of the plugin (the key in the `plugins:` collection) that produced this file. This attribute is populated automatically when using the `File.generated()` constructor.
+*   There is a new attribute [`File.generated_by`][mkdocs.structure.files.File.generated_by] that arose by convention - for generated files it should be set to the name of the plugin (the key in the `plugins:` collection) that produced this file. This attribute is populated automatically when using the `File.generated()` constructor.
 
-*   It is possible to set the `edit_uri` attribute of a `File`, for example from a plugin or hook, to make it different from the default (equal to `src_uri`), and this will be reflected in the edit link of the document. This can be useful because some pages aren't backed by a real file and are instead created dynamically from some other source file or script. So a hook could set the `edit_uri` to that source file or script accordingly.
+*   It is possible to set the [`edit_uri`][mkdocs.structure.files.File.edit_uri] attribute of a `File`, for example from a plugin or hook, to make it different from the default (equal to `src_uri`), and this will be reflected in the edit link of the document. This can be useful because some pages aren't backed by a real file and are instead created dynamically from some other source file or script. So a hook could set the `edit_uri` to that source file or script accordingly.
 
 *   The `File` object now stores its original `src_dir`, `dest_dir`, `use_directory_urls` values as attributes.
 
-*   Fields of `File` are computed on demand but cached. Only the three above attributes are primary ones, and partly also `dest_uri`. This way, it is possible to, for example, overwrite `dest_uri` of a `File`, and `abs_dest_path` will be calculated based on it. However you need to clear the attribute first using `del f.abs_dest_path`, because the values are cached.
+*   Fields of `File` are computed on demand but cached. Only the three above attributes are primary ones, and partly also [`dest_uri`][mkdocs.structure.files.File.dest_uri]. This way, it is possible to, for example, overwrite `dest_uri` of a `File`, and `abs_dest_path` will be calculated based on it. However you need to clear the attribute first using `del f.abs_dest_path`, because the values are cached.
 
 *   `File` instances are now hashable (can be used as keys of a `dict`). Two files can no longer be considered "equal" unless it's the exact same instance of `File`.
 
-<!-- -->
+Other changes:
 
 *   The internal storage of `File` objects inside a `Files` object has been reworked, so any plugins that choose to access `Files._files` will get a deprecation warning.
 
@@ -210,38 +218,40 @@ Context: #3451, #3463
 
 ### Hooks and debugging
 
-*   Hook files can now import adjacent *.py files using the `import` statement. Previously this was possible to achieve only through a `sys.path` workaround. See the new mention in [documentation](../user-guide/configuration.md#hooks). (#3568)
+*   Hook files can now import adjacent *.py files using the `import` statement. Previously this was possible to achieve only through a `sys.path` workaround. See the new mention in [documentation](../user-guide/configuration.md#hooks). Context: #3568
 
 *   Verbose `-v` log shows the sequence of plugin events in more detail - shows each invoked plugin one by one, not only the event type. Context: #3444
 
 ### Deprecations
 
-Python 3.7 is no longer supported, Python 3.12 is officially supported. Context: #3429
+*   Python 3.7 is no longer supported, Python 3.12 is officially supported. Context: #3429
+
+*   The theme config file `mkdocs_theme.yml` no longer executes YAML tags. Context: #3465
 
-* It is no longer allowed to set `File.page` to a type other than `Page` or a subclass thereof. Context: #3443 - following the deprecation in version 1.5.3 and #3381.
+*   The plugin event `on_page_read_source` is soft-deprecated because there is always a better alternative to it (see the new `File` API or just `on_page_markdown`, depending on the desired interaction).
 
-<!-- -->
+    When multiple plugins/hooks apply this event handler, they trample over each other, so now there is a warning in that case.
 
-* `Theme._vars` is deprecated - use `theme['foo']` instead of `theme._vars['foo']`
-* `utils`: `modified_time()`, `get_html_path()`, `get_url_path()`, `is_html_file()`, `is_template_file()` are removed. `path_to_url()` is deprecated.
-* `LiveReloadServer.watch()` no longer accepts a custom callback.
+    See [**documentation**](../dev-guide/plugins.md#on_page_read_source). Context: #3503
 
-Context: #3429
+#### API deprecations
 
-* The theme config file `mkdocs_theme.yml` no longer executes YAML tags. Context: #3465
+*   It is no longer allowed to set `File.page` to a type other than `Page` or a subclass thereof. Context: #3443 - following the deprecation in version 1.5.3 and #3381.
 
-<!-- -->
+*   `Theme._vars` is deprecated - use `theme['foo']` instead of `theme._vars['foo']`
 
-*   The plugin event `on_page_read_source` is soft-deprecated because there is always a better alternative to it (see the new `File` API or just `on_page_markdown`, depending on the desired interaction).
+*   `utils`: `modified_time()`, `get_html_path()`, `get_url_path()`, `is_html_file()`, `is_template_file()` are removed. `path_to_url()` is deprecated.
 
-    When multiple plugins/hooks apply this event handler, they trample over each other, so now there is a warning in that case.
+*   `LiveReloadServer.watch()` no longer accepts a custom callback.
 
-    See [**documentation**](../dev-guide/plugins.md#on_page_read_source). Context: #3503
+Context: #3429
 
 ### Misc
 
 * The `sitemap.xml.gz` file is slightly more reproducible and no longer changes on every build, but instead only once per day (upon a date change). Context: #3460
 
+Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/compare/1.5.3...1.6.0).
+
 ## Version 1.5.3 (2023-09-18)
 
 *   Fix `mkdocs serve` sometimes locking up all browser tabs when navigating quickly (#3390)

mkdocs/__init__.py

@@ -2,4 +2,4 @@
 
 
 # For acceptable version formats, see https://www.python.org/dev/peps/pep-0440/
-__version__ = '1.5.3'
+__version__ = '1.6.0'

mkdocs/structure/files.py

@@ -354,6 +354,12 @@ def __repr__(self):
 
     @utils.weak_property
     def edit_uri(self) -> str | None:
+        """
+        A path relative to the source repository to use for the "edit" button.
+
+        Defaults to `src_uri` and can be overwritten.
+        For generated files this should be set to `None`.
+        """
         return self.src_uri if self.generated_by is None else None
 
     def _get_stem(self) -> str:

mkdocs/structure/pages.py

@@ -231,7 +231,8 @@ def title(self) -> str | None:  # type: ignore[override]
 
         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:
+        Checks these in order and uses the first that returns a valid title:
+
         - value provided on init (passed in from config)
         - value of metadata 'title'
         - content of the first H1 in Markdown content