Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use key value syntax for Insider plugins example #3783

Merged
merged 4 commits into from Apr 6, 2022
Merged

Use key value syntax for Insider plugins example #3783

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
51f56d9
Add warning about merging sections between files
cicdw Apr 1, 2022
2b34920
Use full example with alternative syntax
cicdw Apr 6, 2022
0b21281
Revert accidentally commited changes
cicdw Apr 6, 2022
1491614
Revert another accidental commit
cicdw Apr 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/insiders/getting-started.md
View file
Open in desktop
Expand Up @@ -185,4 +185,17 @@ pipeline), you can build your documentation project with the following lines:
mkdocs build --config-file mkdocs.insiders.yml
```

!!! warning "Alternative syntax"

If you plan to split `plugins` or `markdown_extensions` between the two files, you must use
alternative key / value syntax for these sections. The above insiders file would then look like:
``` yaml
INHERIT: mkdocs.yml
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we maybe provide two code blocks each for each mkdocs.yml file (base + Insiders overrides) which just adds the social plugin? The other plugins are non-Insiders anyway. This would be a more self-contained example for the user to understand how to do overrides while keeping the plugin configuration of the base configuration. I say we could just add the social plugin as an example. Otherwise, users might start to mix syntaxes, or is that possible?

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So essentially something like:

mkdocs.yml

plugins:
  search: {}
  tags: {}

mkdocs.insiders.yml

INHERIT: mkdocs.yml
plugins:
  social {}

Please use the content tabs pattern for this, as in other parts of the documentation.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your patience with my slow updates - I just pushed the requested changes!

plugins:
search: {}
social: {}
tags: {}
```


[configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance