Merge remote-tracking branch 'origin/master' into htitle

README.md

@@ -29,7 +29,7 @@ If you need help with MkDocs, do not hesitate to get in contact with us!
 
 - For questions and high-level discussions, use **[Discussions]** on GitHub.
  - For small questions, a good alternative is the **[Chat room]** on
- Gitter/Matrix (**new!**)
+ Gitter/Matrix.
 - To report a bug or make a feature request, open an **[Issue]** on GitHub.
 
 Please note that we may only provide
@@ -44,8 +44,7 @@ Make sure to stick around to answer some questions as well!
 
 - [Official Documentation][mkdocs]
 - [Latest Release Notes][release-notes]
-- [MkDocs Wiki][wiki] (Third-party themes, recipes, plugins and more)
-- [Best-of-MkDocs][best-of] (Curated list of themes, plugins and more)
+- [Best-of-MkDocs][best-of] (Third-party themes, recipes, plugins and more)
 
 ## Contributing to MkDocs
 
@@ -71,10 +70,9 @@ discussion forums is expected to follow the [PyPA Code of Conduct].
 [Discussions]: https://github.com/mkdocs/mkdocs/discussions
 [Chat room]: https://gitter.im/mkdocs/community
 [release-notes]: https://www.mkdocs.org/about/release-notes/
-[wiki]: https://github.com/mkdocs/mkdocs/wiki
 [Contributing Guide]: https://www.mkdocs.org/about/contributing/
 [PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/
-[best-of]: https://github.com/pawamoy/best-of-mkdocs
+[best-of]: https://github.com/mkdocs/best-of-mkdocs
 
 ## License
 

docs/about/contributing.md

@@ -86,11 +86,12 @@ with `{% trans %}` and `{% endtrans %}` tags.
 
 Each time a translatable text placeholder is added, removed or changed in a
 theme template, the theme's Portable Object Template (`pot`) file needs to be
-updated by running the `extract_messages` command. For example, to update the
-`pot` file of the `mkdocs` theme, run the following command:
+updated by running the `extract_messages` command. To update the
+`pot` file for both built-in themes, run these commands:
 
 ```bash
 pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs
+pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs
 ```
 
 The updated `pot` file should be included in a PR with the updated template.

docs/about/release-notes.md

@@ -27,6 +27,23 @@ The current and past members of the MkDocs team.
 * [@oprypin](https://github.com/oprypin/)
 * [@ultrabug](https://github.com/ultrabug/)
 
+## Version 1.4.3 (2023-05-02)
+
+* Bugfix: for the `hooks` feature, modules no longer fail to load if using some advanced Python features like dataclasses (#3193)
+
+* Bugfix: Don't create `None` sitemap entries if the page has no populated URL - affects sites that exclude some files from navigation ([`07a297b`](https://github.com/mkdocs/mkdocs/commit/07a297b3b4de4a1b49469b1497ee34039b9f38fa))
+
+* "readthedocs" theme:
+ * Accessibility: add aria labels to Home logo (#3129) and search inputs (#3046)
+ * "readthedocs" theme now supports `hljs_style:` config, same as "mkdocs" theme (#3199)
+
+* Translations:
+ * Built-in themes now also support Indonesian language (#3154)
+ * Fixed `zh_CN` translation (#3125)
+ * `tr_TR` translation becomes just `tr` - usage should remain unaffected (#3195)
+
+See [commit log](https://github.com/mkdocs/mkdocs/compare/1.4.2...1.4.3).
+
 ## Version 1.4.2 (2022-11-01)
 
 * Officially support Python 3.11 (#3020)
@@ -1525,7 +1542,7 @@ a small subset of the configuration options can be passed to the commands. To
 see in full commands and available arguments use `mkdocs --help` and
 `mkdocs build --help` to have them displayed.
 
-[Click]: http://click.pocoo.org/4/
+[Click]: https://click.palletsprojects.com/
 
 #### Support Extra HTML and XML files
 

docs/dev-guide/plugins.md

@@ -16,8 +16,8 @@ pip install mkdocs-foo-plugin
 ```
 
 Once a plugin has been successfully installed, it is ready to use. It just needs
-to be [enabled](#using-plugins) in the configuration file. The [MkDocs Plugins]
-wiki page has a growing list of plugins that you can install and use.
+to be [enabled](#using-plugins) in the configuration file. The [Best-of-MkDocs]
+page has a large list of plugins that you can install and use.
 
 ## Using Plugins
 
@@ -519,5 +519,5 @@ tell MkDocs to use it via the config.
 [post_template]: #on_post_template
 [static_templates]: ../user-guide/configuration.md#static_templates
 [Template Events]: #template-events
-[MkDocs Plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
+[Best-of-MkDocs]: https://github.com/mkdocs/best-of-mkdocs
 [on_build_error]: #on_build_error

docs/dev-guide/themes.md

@@ -6,8 +6,8 @@ A guide to creating and distributing custom themes.
 
 NOTE:
 If you are looking for existing third party themes, they are listed in the
-MkDocs [community wiki]. If you want to share a theme you create, you
-should list it on the Wiki.
+[community wiki] page and [Best-of-MkDocs]. If you want to share a theme you create, you
+should list it there.
 
 When creating a new theme, you can either follow the steps in this guide to
 create one from scratch or you can download the `mkdocs-basic-theme` as a
@@ -16,6 +16,7 @@ this base theme on [GitHub][basic theme]**. It contains detailed comments in
 the code to describe the different features and their usage.
 
 [community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
+[Best-of-MkDocs]: https://github.com/mkdocs/best-of-mkdocs#-theming
 [basic theme]: https://github.com/mkdocs/mkdocs-basic-theme
 
 ## Creating a custom theme
@@ -111,8 +112,8 @@ 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
 themes for consistency.
 
-[Jinja]: http://jinja.pocoo.org/
-[template inheritance]: http://jinja.pocoo.org/docs/dev/templates/#template-inheritance
+[Jinja]: https://jinja.palletsprojects.com/
+[template inheritance]: https://jinja.palletsprojects.com/en/latest/templates/#template-inheritance
 [blocks]: ../user-guide/customizing-your-theme.md#overriding-template-blocks
 
 ## Theme Files
@@ -727,7 +728,7 @@ created if the user explicitly enables the [prebuild_index] config option.
 Themes should expect the index to not be present, but can choose to use the
 index when it is available. The `index` object was new in MkDocs version *1.0*.
 
-[Jinja2 template]: http://jinja.pocoo.org/docs/dev/
+[Jinja2 template]: https://jinja.palletsprojects.com/
 [built-in themes]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes
 [theme's configuration file]: #theme-configuration
 [lunr.js]: https://lunrjs.com/

docs/dev-guide/translations.md

@@ -41,7 +41,7 @@ Make sure translation requirements are installed in your environment:
 pip install mkdocs[i18n]
 ```
 
-[babel]: http://babel.pocoo.org/en/latest/cmdline.html
+[babel]: https://babel.pocoo.org/en/latest/cmdline.html
 [Contributing Guide]: ../about/contributing.md
 [Install for Development]: ../about/contributing.md#installing-for-development
 [Submit a Pull Request]: ../about/contributing.md#submitting-pull-requests
@@ -54,11 +54,12 @@ translation by following the steps below.
 
 Here is a quick summary of what you'll need to do:
 
-1. [Initialize new localization catalogs](#initializing-the-localization-catalogs) for your language (if a translation for your locale already exists, follow the instructions for [updating theme localization files](/user-guide/custom-themes/#localizing-themes) instead).
-2. [Add a translation](#translating-the-mkdocs-themes) for every text placeholder in the localized catalogs.
-3. [Locally serve and test](#testing-theme-translations) the translated themes for your language.
-4. [Update the documentation](#updating-theme-documentation) about supported translations for each translated theme.
-5. [Contribute your translation](#contributing-translations) through a Pull Request.
+1. [Fork and clone the MkDocs repository](#fork-and-clone-the-mkdocs-repository) and then [install MkDocs for development](/about/contributing/#installing-for-development) for adding and testing translations.
+2. [Initialize new localization catalogs](#initializing-the-localization-catalogs) for your language (if a translation for your locale already exists, follow the instructions for [updating theme localization files](/user-guide/custom-themes/#localizing-themes) instead).
+3. [Add a translation](#translating-the-mkdocs-themes) for every text placeholder in the localized catalogs.
+4. [Locally serve and test](#testing-theme-translations) the translated themes for your language.
+5. [Update the documentation](#updating-theme-documentation) about supported translations for each translated theme.
+6. [Contribute your translation](#contributing-translations) through a Pull Request.
 
 NOTE:
 Translation locales are usually identified using the [ISO-639-1] (2-letter)
@@ -69,6 +70,15 @@ use of a term which differs from the general language translation.
 
 [ISO-639-1]: https://en.wikipedia.org/wiki/ISO_639-1
 
+### Fork and clone the MkDocs repository
+
+In the following steps you'll work with a fork of the MkDocs repository. Follow
+the instructions for [forking and cloning the MkDocs
+repository](/about/contributing/#installing-for-development).
+
+To test the translations you also need to [install MkDocs for
+development](/about/contributing/#installing-for-development) from your fork.
+
 ### Initializing the localization catalogs
 
 The templates for each theme contain text placeholders that have been extracted
@@ -79,15 +89,26 @@ Initializing a catalog consists of running a command which will create a
 directory structure for your desired language and prepare a Portable Object
 (`messages.po`) file derived from the `pot` file of the theme.
 
-Use the `init_catalog` command on each theme's directory and provide the
-appropriate language code (`-l <language>`). For example, to add a translation
-for the Spanish `es` language to the `mkdocs` theme, run the following command:
+Use the `init_catalog` command on each theme's directory and provide the appropriate language code (`-l <language>`).
+
+The language code is almost always just two lowercase letters, such as `sv`, but in some cases it needs to be further disambiguated.
+
+See:
+
+* [Already translated languages for built-in themes](../user-guide/choosing-your-theme.md#mkdocs-locale)
+* [ISO 639 Language List](https://www.localeplanet.com/icu/iso639.html)
+* [Language subtag registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)
+
+In particular, the way to know that the `pt` language should be disambiguated as `pt_PT` and `pt_BR` is that the *Language subtag registry* page contains `pt-` if you search for it. Whereas `sv` should remain just `sv`, because that page does *not* contain `sv-`.
+
+So, if we pick `es` (Spanish) as our example language code, to add a translation for it to both built-in themes, run these commands:
 
 ```bash
-pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales --locale es
+pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l es
+pybabel init --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l es
 ```
 
-The above command will create the following file structure:
+The above command will create a file structure as follows:
 
 ```text
 mkdocs/themes/mkdocs/locales
@@ -117,11 +138,11 @@ This step should be completed after a theme template have been [updated][update
 themes] for each language that you are comfortable contributing a translation
 for.
 
-To update the `fr` translation catalog of the `mkdocs` theme, use the following
-command:
+To update the `fr` translation catalog of both built-in themes, use the following commands:
 
 ```bash
-pybabel update --ignore-obsolete --update-header-comment --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales --locale fr
+pybabel update --ignore-obsolete --update-header-comment --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l fr
+pybabel update --ignore-obsolete --update-header-comment --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l fr
 ```
 
 You can now move on to the next step and [add a translation] for every updated
@@ -149,11 +170,12 @@ you'll want to [test your localized theme](#testing-theme-translations).
 ### Testing theme translations
 
 To test a theme with translations, you need to first compile the `messages.po`
-files of your theme into `messages.mo` files. The following command will compile
-the `es` translation for the `mkdocs` theme.
+files of your theme into `messages.mo` files. The following commands will compile
+the `es` translation for both built-in themes:
 
 ```bash
-pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales --locale es
+pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales -l es
+pybabel compile --statistics --directory mkdocs/themes/readthedocs/locales -l es
 ```
 
 The above command results in the following file structure:

docs/index.md

@@ -27,15 +27,14 @@ configuration file. Start by reading the [introductory tutorial], then check the
   <div class="card-body">
   <h3 class="card-title">Great themes available</h3>
   <p class="card-text">
-  There's a stack of good looking <a
-  href="user-guide/choosing-your-theme">themes</a> available for
-  MkDocs. Choose between the built in themes: <a
-  href="user-guide/choosing-your-theme/#mkdocs">mkdocs</a> and <a
-  href="user-guide/choosing-your-theme/#readthedocs">readthedocs</a>,
-  select one of the third-party themes listed on the <a
-  href="https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes">MkDocs
-  Themes</a> wiki page, or <a href="dev-guide/themes/">build your
-  own</a>.
+  There's a stack of good looking <a href="user-guide/choosing-your-theme">themes</a> available for MkDocs.
+  Choose between the built in themes:
+  <a href="user-guide/choosing-your-theme/#mkdocs">mkdocs</a> and
+  <a href="user-guide/choosing-your-theme/#readthedocs">readthedocs</a>,
+  select one of the third-party themes
+  (on the <a href="https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes">MkDocs Themes</a> wiki page
+  as well as <a href="https://github.com/mkdocs/best-of-mkdocs#-theming">Best-of-MkDocs</a>),
+  or <a href="dev-guide/themes/">build your own</a>.
   </p>
   </div>
  </div>

docs/user-guide/choosing-your-theme.md

@@ -102,7 +102,7 @@ supports the following options:
  ```
 
 * __`locale`__{ #mkdocs-locale }: The locale (language/location) used to
- build the theme. If your locale is not yet supported, it will fallback
+ build the theme. If your locale is not yet supported, it will fall back
  to the default.
 
  The following locales are supported by this theme:
@@ -112,13 +112,14 @@ supports the following options:
  * `es`: Spanish
  * `fa`: Persian (Farsi)
  * `fr`: French
+ * `id`: Indonesian
  * `it`: Italian
  * `ja`: Japanese
  * `nb`: Norwegian Bokmål
  * `nn`: Norwegian Nynorsk
  * `pt_BR`: Portuguese (Brazil)
  * `ru`: Russian
- * `tr_TR`: Turkish (Turkey)
+ * `tr`: Turkish
  * `uk`: Ukrainian
  * `zh_CN`: Simplified Chinese
 
@@ -191,23 +192,24 @@ theme supports the following options:
  page content as you scroll the page. Default: `True`.
 
 * __`locale`__{ #readthedocs-locale }: The locale (language/location) used to
- build the theme. If your locale is not yet supported, it will fallback
+ build the theme. If your locale is not yet supported, it will fall back
  to the default.
 
  The following locales are supported by this theme:
 
  * `en`: English (default)
- * `fr`: French
- * `es`: Spanish
- * `ja`: Japanese
- * `pt_BR`: Portuguese (Brazil)
- * `zh_CN`: Simplified Chinese
  * `de`: German
+ * `es`: Spanish
  * `fa`: Persian (Farsi)
+ * `fr`: French
+ * `id`: Indonesian
  * `it`: Italian
- * `tr_TR`: Turkish (Turkey)
+ * `ja`: Japanese
+ * `pt_BR`: Portuguese (Brazil)
  * `ru`: Russian
+ * `tr`: Turkish
  * `uk`: Ukrainian
+ * `zh_CN`: Simplified Chinese
 
  See the guide on [localizing your theme] for more information.
 
@@ -216,8 +218,7 @@ theme supports the following options:
 
 ## Third Party Themes
 
-A list of third party themes can be found in the MkDocs [community wiki]. If you
-have created your own, please feel free to add it to the list.
+A list of third party themes can be found at the [community wiki] page and [Best-of-MkDocs]. If you have created your own, please add them there.
 
 [third party themes]: #third-party-themes
 [theme]: configuration.md#theme
@@ -228,4 +229,5 @@ have created your own, please feel free to add it to the list.
 [upgrade-GA4]: https://support.google.com/analytics/answer/9744165?hl=en&ref_topic=9303319
 [Read the Docs]: https://readthedocs.org/
 [community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
+[Best-of-MkDocs]: https://github.com/mkdocs/best-of-mkdocs#-theming
 [localizing your theme]: localizing-your-theme.md

docs/user-guide/configuration.md

@@ -575,7 +575,7 @@ This alternative syntax is required if you intend to override some options via
 > which are available out-of-the-box. For a list of configuration options
 > available for a given extension, see the documentation for that extension.
 >
-> You may also install and use various [third party extensions][3rd]. Consult
+> You may also install and use various third party extensions ([Python-Markdown wiki], [Best-of-MkDocs]). Consult
 > the documentation provided by those extensions for installation instructions
 > and available configuration options.
 
@@ -963,7 +963,8 @@ path based options in the primary configuration file only.
 [pymkd]: https://python-markdown.github.io/
 [smarty]: https://python-markdown.github.io/extensions/smarty/
 [exts]: https://python-markdown.github.io/extensions/
-[3rd]: https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions
+[Python-Markdown wiki]: https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions
+[Best-of-MkDocs]: https://github.com/mkdocs/best-of-mkdocs
 [configuring pages and navigation]: writing-your-docs.md#configure-pages-and-navigation
 [theme_dir]: customizing-your-theme.md#using-the-theme_dir
 [choosing your theme]: choosing-your-theme.md

docs/user-guide/customizing-your-theme.md

@@ -28,7 +28,7 @@ h1 {
 ```
 
 > NOTE:
-> If you are deploying your documentation with [ReadTheDocs]. You will need
+> If you are deploying your documentation with [ReadTheDocs], you will need
 > to explicitly list the CSS and JavaScript files you want to include in
 > your config. To do this, add the following to your mkdocs.yml.
 >
@@ -224,6 +224,6 @@ any additional CSS files included in the `custom_dir`.
 [mkdocs]: ./choosing-your-theme.md#mkdocs
 [browse source]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs
 [Template Variables]: ../dev-guide/themes.md#template-variables
-[Jinja documentation]: http://jinja.pocoo.org/docs/dev/templates/#template-inheritance
-[super block]: http://jinja.pocoo.org/docs/dev/templates/#super-blocks
+[Jinja documentation]: https://jinja.palletsprojects.com/en/latest/templates/#template-inheritance
+[super block]: https://jinja.palletsprojects.com/en/latest/templates/#super-blocks
 [base_url]: ../dev-guide/themes.md#base_url

docs/user-guide/writing-your-docs.md

@@ -463,8 +463,8 @@ detected, but the content between the delimiters is not valid YAML
 meta-data, MkDocs does not attempt to parse the content as MultiMarkdown
 style meta-data.
 
-[YAML]: http://yaml.org
-[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata
+[YAML]: https://yaml.org
+[MultiMarkdown]: https://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata
 [nav]: configuration.md#nav
 
 ### Tables