From cd1135ee3e536d8b60c4a3deb66735b279b71b84 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Sun, 7 Aug 2022 14:46:10 +0200 Subject: [PATCH] Fix remaining markdownlint issues, partly by replacing definition lists (#2914) --- docs/about/release-notes.md | 9 ----- docs/dev-guide/plugins.md | 50 ++++++++++++++-------------- docs/dev-guide/themes.md | 3 -- docs/user-guide/configuration.md | 16 +++------ docs/user-guide/writing-your-docs.md | 20 +++++------ 5 files changed, 40 insertions(+), 58 deletions(-) diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 418ddcfe..988e0a1b 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -975,15 +975,6 @@ user created and third-party templates: | previous_page | [page.previous_page]| | next_page | [page.next_page] | -[page]: ../dev-guide/themes.md#page -[page.title]: ../dev-guide/themes.md#pagetitle -[page.content]: ../dev-guide/themes.md#pagecontent -[page.toc]: ../dev-guide/themes.md#pagetoc -[page.meta]: ../dev-guide/themes.md#pagemeta -[page.canonical_url]: ../dev-guide/themes.md#pagecanonical_url -[page.previous_page]: ../dev-guide/themes.md#pageprevious_page -[page.next_page]: ../dev-guide/themes.md#pagenext_page - ##### Global Context Additionally, a number of global variables have been altered and/or deprecated diff --git a/docs/dev-guide/plugins.md b/docs/dev-guide/plugins.md index 79ed2979..1f63b1fa 100644 --- a/docs/dev-guide/plugins.md +++ b/docs/dev-guide/plugins.md @@ -68,7 +68,7 @@ All `BasePlugin` subclasses contain the following attributes: #### config_scheme -: A tuple of configuration validation instances. Each item must consist of a +* A tuple of configuration validation instances. Each item must consist of a two item tuple in which the first item is the string name of the configuration option and the second item is an instance of `mkdocs.config.config_options.BaseConfigOption` or any of its subclasses. @@ -93,7 +93,7 @@ All `BasePlugin` subclasses contain the following attributes: #### config -: A dictionary of configuration options for the plugin, which is populated by +* A dictionary of configuration options for the plugin, which is populated by the `load_config` method after configuration validation has completed. Use this attribute to access options provided by the user. @@ -105,13 +105,13 @@ All `BasePlugin` subclasses contain the following method(s): #### load_config(options) -: Loads configuration from a dictionary of options. Returns a tuple of +* Loads configuration from a dictionary of options. Returns a tuple of `(errors, warnings)`. This method is called by MkDocs during configuration validation and should not need to be called by the plugin. #### on_<event_name>() -: Optional methods which define the behavior for specific [events]. The plugin +* Optional methods which define the behavior for specific [events]. The plugin should define its behavior within these methods. Replace `` with the actual name of the event. For example, the `pre_build` event would be defined in the `on_pre_build` method. @@ -147,7 +147,7 @@ entire site. ##### on_serve -: The `serve` event is only called when the `serve` command is used during +* The `serve` event is only called when the `serve` command is used during development. It is passed the `Server` instance which can be modified before it is activated. For example, additional files or directories could be added to the list of "watched" files for auto-reloading. @@ -162,7 +162,7 @@ entire site. ##### on_config -: The `config` event is the first event called on build and is run immediately +* The `config` event is the first event called on build and is run immediately after the user configuration is loaded and validated. Any alterations to the config should be made here. @@ -174,7 +174,7 @@ entire site. ##### on_pre_build -: The `pre_build` event does not alter any variables. Use this event to call +* The `pre_build` event does not alter any variables. Use this event to call pre-build scripts. Parameters: @@ -182,7 +182,7 @@ entire site. ##### on_files -: The `files` event is called after the files collection is populated from the +* The `files` event is called after the files collection is populated from the `docs_dir`. Use this event to add, remove, or alter files in the collection. Note that Page objects have not yet been associated with the file objects in the collection. Use [Page Events] to manipulate page @@ -197,7 +197,7 @@ entire site. ##### on_nav -: The `nav` event is called after the site navigation is created and can +* The `nav` event is called after the site navigation is created and can be used to alter the site navigation. Parameters: @@ -210,7 +210,7 @@ entire site. ##### on_env -: The `env` event is called after the Jinja template environment is created +* The `env` event is called after the Jinja template environment is created and can be used to alter the [Jinja environment](https://jinja.palletsprojects.com/en/latest/api/#jinja2.Environment). Parameters: @@ -223,7 +223,7 @@ entire site. ##### on_post_build -: The `post_build` event does not alter any variables. Use this event to call +* The `post_build` event does not alter any variables. Use this event to call post-build scripts. Parameters: @@ -231,7 +231,7 @@ entire site. ##### on_build_error -: The `build_error` event is called after an exception of any kind +* The `build_error` event is called after an exception of any kind is caught by MkDocs during the build process. Use this event to clean things up before MkDocs terminates. Note that any other events which were scheduled to run after the error will have been skipped. See @@ -249,7 +249,7 @@ called after the [env] event and before any [page events]. ##### on_pre_template -: The `pre_template` event is called immediately after the subject template is +* The `pre_template` event is called immediately after the subject template is loaded and can be used to alter the template. Parameters: @@ -262,7 +262,7 @@ called after the [env] event and before any [page events]. ##### on_template_context -: The `template_context` event is called immediately after the context is created +* The `template_context` event is called immediately after the context is created for the subject template and can be used to alter the context for that specific template only. @@ -276,7 +276,7 @@ called after the [env] event and before any [page events]. ##### on_post_template -: The `post_template` event is called after the template is rendered, but before +* The `post_template` event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the template. If an empty string is returned, the template is skipped and nothing is is written to disc. @@ -297,7 +297,7 @@ page events are called after the [post_template] event and before the ##### on_pre_page -: The `pre_page` event is called before any actions are taken on the subject +* The `pre_page` event is called before any actions are taken on the subject page and can be used to alter the `Page` instance. Parameters: @@ -310,7 +310,7 @@ page events are called after the [post_template] event and before the ##### on_page_read_source -: The `on_page_read_source` event can replace the default mechanism to read +* The `on_page_read_source` event can replace the default mechanism to read the contents of a page's source from the filesystem. Parameters: @@ -323,7 +323,7 @@ page events are called after the [post_template] event and before the ##### on_page_markdown -: The `page_markdown` event is called after the page's markdown is loaded +* The `page_markdown` event is called after the page's markdown is loaded from file and can be used to alter the Markdown source text. The meta- data has been stripped off and is available as `page.meta` at this point. @@ -338,7 +338,7 @@ page events are called after the [post_template] event and before the ##### on_page_content -: The `page_content` event is called after the Markdown text is rendered to +* The `page_content` event is called after the Markdown text is rendered to HTML (but before being passed to a template) and can be used to alter the HTML body of the page. @@ -353,7 +353,7 @@ page events are called after the [post_template] event and before the ##### on_page_context -: The `page_context` event is called after the context for a page is created +* The `page_context` event is called after the context for a page is created and can be used to alter the context for that specific page only. Parameters: @@ -367,7 +367,7 @@ page events are called after the [post_template] event and before the ##### on_post_page -: The `post_page` event is called after the template is rendered, but +* The `post_page` event is called after the template is rendered, but before it is written to disc and can be used to alter the output of the page. If an empty string is returned, the page is skipped and nothing is written to disc. @@ -386,23 +386,23 @@ MkDocs defines four error types: #### `mkdocs.exceptions.MkDocsException` -: The base class which all MkDocs exceptions inherit from. This should +* The base class which all MkDocs exceptions inherit from. This should not be raised directly. One of the subclasses should be raised instead. #### `mkdocs.exceptions.ConfigurationError` -: This error is raised by configuration validation when a validation error +* This error is raised by configuration validation when a validation error is encountered. This error should be raised by any configuration options defined in a plugin's [config_scheme]. #### `mkdocs.exceptions.BuildError` -: This error may be raised by MkDocs during the build process. Plugins should +* This error may be raised by MkDocs during the build process. Plugins should not raise this error. #### `mkdocs.exceptions.PluginError` -: A subclass of `mkdocs.exceptions.BuildError` which can be raised by plugin +* A subclass of `mkdocs.exceptions.BuildError` which can be raised by plugin events. Unexpected and uncaught exceptions will interrupt the build process and produce diff --git a/docs/dev-guide/themes.md b/docs/dev-guide/themes.md index f2343d3d..7d3e7554 100644 --- a/docs/dev-guide/themes.md +++ b/docs/dev-guide/themes.md @@ -113,7 +113,6 @@ themes for consistency. [Jinja]: http://jinja.pocoo.org/ [template inheritance]: http://jinja.pocoo.org/docs/dev/templates/#template-inheritance -[theme_dir]: ../user-guide/customizing-your-theme.md#using-the-theme_dir [blocks]: ../user-guide/customizing-your-theme.md#overriding-template-blocks ## Theme Files @@ -902,7 +901,6 @@ For a much more detailed guide, see the official Python packaging documentation for [Packaging and Distributing Projects]. [Packaging and Distributing Projects]: https://packaging.python.org/en/latest/distributing/ -[theme]: ../user-guide/configuration.md#theme [Jinja inheritance rules]: https://jinja.palletsprojects.com/en/latest/templates/#template-inheritance ## Supporting theme Localization/Translation @@ -921,7 +919,6 @@ built-in themes, the sections below outline how to enable and make use of the same commands utilized by MkDocs. [localization/translation]: ../user-guide/localizing-your-theme.md -[Theme Configuration]: #theme-configuration ### Enabling the Localization/Translation commands diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 3821024e..953ce14f 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -242,17 +242,17 @@ If a set of key/value pairs, the following nested keys can be defined: > BLOCK: > -> #### name: +> #### name > > The string name of a known installed theme. For a list of available themes > visit [Choosing Your Theme]. > -> #### locale: +> #### locale > > A code representing the language of your site. See [Localizing your theme] > for details. > -> #### custom_dir: +> #### custom_dir > > A directory containing a custom theme. This can either be a relative > directory, in which case it is resolved relative to the directory containing @@ -265,7 +265,7 @@ If a set of key/value pairs, the following nested keys can be defined: > See the [Theme Developer Guide] if you would like to build your own theme > from the ground up. > -> #### static_templates: +> #### static_templates > > A list of templates to render as static pages. The templates must be located > in either the theme's template directory or in the `custom_dir` defined in @@ -651,8 +651,6 @@ significant improvement in search performance. **default**: `False` -[Node.js]: https://nodejs.org/ - ##### **indexing** Configures what strategy the search indexer will use when building the index @@ -726,7 +724,7 @@ primary file. For configuration options to be merged with a parent configuration, those options must be defined as key/value pairs. Specifically, the -[markdown_extensions] and [plugins] options must use the alternative syntax +[markdown_extensions] and [plugins](#plugins) options must use the alternative syntax which does not use list items (lines which start with `-`). For example, suppose the common (parent) configuration is defined in `base.yml`: @@ -830,7 +828,6 @@ different sites may not work as expected. It is generally best to define path based options in the primary configuration file only. [Theme Developer Guide]: ../dev-guide/themes.md -[variables that are available]: ../dev-guide/themes.md#template-variables [pymdk-extensions]: https://python-markdown.github.io/extensions/ [pymkd]: https://python-markdown.github.io/ [smarty]: https://python-markdown.github.io/extensions/smarty/ @@ -847,9 +844,6 @@ path based options in the primary configuration file only. [Lunr Languages]: https://github.com/MihaiValentin/lunr-languages#lunr-languages----- [contribute additional languages]: https://github.com/MihaiValentin/lunr-languages/blob/master/CONTRIBUTING.md [Node.js]: https://nodejs.org/ -[Lunr.py]: http://lunr.readthedocs.io/ -[Lunr.py's issues]: https://github.com/yeraydiazdiaz/lunr.py/issues [markdown_extensions]: #markdown_extensions -[plugins]: #plugins [nav]: #nav [inheritance]: #configuration-inheritance diff --git a/docs/user-guide/writing-your-docs.md b/docs/user-guide/writing-your-docs.md index cb55a801..3dd9370d 100644 --- a/docs/user-guide/writing-your-docs.md +++ b/docs/user-guide/writing-your-docs.md @@ -243,9 +243,9 @@ dashes. Consecutive dashes are then reduced to a single dash. There are a few configuration settings provided by the toc extension which you can set in your `mkdocs.yml` configuration file to alter the default behavior: -`permalink`: +* **`permalink`** -: Generate permanent links at the end of each header. Default: `False`. + Generate permanent links at the end of each header. Default: `False`. When set to True the paragraph symbol (¶ or `¶`) is used as the link text. When set to a string, the provided string is used as the link @@ -255,9 +255,9 @@ can set in your `mkdocs.yml` configuration file to alter the default behavior: - toc: permalink: "#" -`baselevel`: +* **`baselevel`** -: Base level for headers. Default: `1`. + Base level for headers. Default: `1`. This setting allows the header levels to be automatically adjusted to fit within the hierarchy of your HTML templates. For example, if the Markdown @@ -272,9 +272,9 @@ can set in your `mkdocs.yml` configuration file to alter the default behavior: header `# Header` would be rendered as a level 2 header (`

`) in the HTML output. -`separator`: +* **`separator`** -: Word separator. Default: `-`. + Word separator. Default: `-`. Character which replaces white-space in generated IDs. If you prefer underscores, then do: @@ -358,18 +358,18 @@ In addition to displaying information in a template, MkDocs includes support for a few predefined meta-data keys which can alter the behavior of MkDocs for that specific page. The following keys are supported: -`template`: +* **`template`** -: The template to use with the current page. + The template to use with the current page. By default, MkDocs uses the `main.html` template of a theme to render Markdown pages. You can use the `template` meta-data key to define a different template file for that specific page. The template file must be available on the path(s) defined in the theme's environment. -`title`: +* **`title`** -: The "title" to use for the document. + The "title" to use for the document. MkDocs will attempt to determine the title of a document in the following ways, in order: