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

Fix remaining markdownlint issues, partly by replacing definition lists (#2914)

Browse Source
This commit is contained in:
Oleh Prypin
2022-08-07 14:46:10 +02:00
committed by GitHub
parent c04dc81039
commit cd1135ee3e
5 changed files with 40 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/about/release-notes.md
View File

@@ -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

50
docs/dev-guide/plugins.md
View File

@@ -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 `<event_name>` 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

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

@@ -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

16
docs/user-guide/configuration.md
View File

@@ -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

20
docs/user-guide/writing-your-docs.md
View File

@@ -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 (&para; or `&para;`) 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 (`<h2>`) 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: