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

Add documentation for type-checked configs

Browse Source
This commit is contained in:
Oleh Prypin
2022-08-21 19:33:46 +02:00
parent e160c47962
commit a4c1bb14dc
1 changed files with 36 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -86,6 +86,20 @@ All `BasePlugin` subclasses contain the following attributes:
)
```
> NEW: **New in version 1.4.**
>
> To get type safety benefits, if you're targeting only MkDocs 1.4+, define the config schema as a class instead:
>
> ```python
> class MyPluginConfig(mkdocs.config.base.Config):
> foo = mkdocs.config.config_options.Type(str, default='a default value')
> bar = mkdocs.config.config_options.Type(int, default=0)
> baz = mkdocs.config.config_options.Type(bool, default=True)
>
> class MyPlugin(mkdocs.plugins.BasePlugin[MyPluginConfig]):
> ...
> ```
When the user's configuration is loaded, the above scheme will be used to
validate the configuration and fill in any defaults for settings not
provided by the user. The validation classes may be any of the classes
@@ -103,10 +117,20 @@ All `BasePlugin` subclasses contain the following attributes:
```python
def on_pre_build(self, config, **kwargs):
if self.config['bool_option']:
# implement "bool_option" functionality here...
if self.config['baz']:
# implement "baz" functionality here...
```
> NEW: **New in version 1.4.**
>
> To get type safety benefits, if you're targeting only MkDocs 1.4+, access options as attributes instead:
>
> ```python
> def on_pre_build(self, config, **kwargs):
> if self.config.baz:
> print(self.config.bar ** 2)
> ```
All `BasePlugin` subclasses contain the following method(s):
#### load_config(options)
@@ -142,6 +166,16 @@ All `BasePlugin` subclasses contain the following method(s):
return config
```
> NEW: **New in version 1.4.**
>
> To get type safety benefits, if you're targeting only MkDocs 1.4+, access config options as attributes instead:
>
> ```python
> def on_config(self, config: MkDocsConfig):
> config.theme.static_templates.add('my_template.html')
> return config
> ```
### Events
There are three kinds of events: [Global Events], [Page Events] and