Skip to content

Support running existing mkdocs plugins and themes#15

Merged
oprypin merged 2 commits intomasterfrom
plugins
Mar 14, 2026
Merged

Support running existing mkdocs plugins and themes#15
oprypin merged 2 commits intomasterfrom
plugins

Conversation

@oprypin
Copy link
Copy Markdown
Member

@oprypin oprypin commented Mar 12, 2026

  • Support running existing mkdocs plugins by redirecting the import

    First of all, support 'mkdocs.plugins' entrypoints but with a lower priority than ours.

    At the start of execution, set up a metaimporter such that whenever a plugin imports anything from 'mkdocs.*', the import gets redirected to us.
    Also keep MkDocsConfig as an alias for the same reason - it was the only renamed class.

  • Support loading existing mkdocs themes

    Simply support the mkdocs.themes entrypoints but give preference to our entrypoints.

    Also, populate the mkdocs_version field for themes but with our project name prefix, to distinguish them if the theme renders this value.

@Andre601
Copy link
Copy Markdown
Contributor

Andre601 commented Mar 14, 2026

Should we perhaps inform users via warnings about "legacy" projects being used if technically possible?

Like WARNING - Legacy MkDocs plugin {plugin} loaded! If possible, use a properdocs alternative or ask the dev to support ProperDocs.

@oprypin
Copy link
Copy Markdown
Member Author

oprypin commented Mar 14, 2026

Yes I have something for that but I realized that it's conceptually worth being in a separate pull request.

Base automatically changed from rename to master March 14, 2026 13:24
oprypin added 2 commits March 14, 2026 14:29
First of all, support 'mkdocs.plugins' entrypoints but with a lower priority than ours.

At the start of execution, set up a metaimporter such that whenever a plugin imports anything from 'mkdocs.*', the import gets redirected to us.
Also keep MkDocsConfig as an alias for the same reason - it was the only renamed class.
Simply support the mkdocs.themes entrypoints but give preference to our entrypoints.

Also, populate the mkdocs_version field for themes but with our project name prefix, to distinguish them if the theme renders this value.
@oprypin oprypin merged commit 7c011cf into master Mar 14, 2026
14 of 34 checks passed
@oprypin oprypin deleted the plugins branch March 14, 2026 13:31
@oprypin
Copy link
Copy Markdown
Member Author

oprypin commented Mar 14, 2026

@Andre601 Oh maybe I misread your message.
I think it would not be good to write this nagging message for almost every plugin. We will also not be forcing plugins to stop supporting mkdocs, it's fine for them to keep support both.
I was thinking the nagging should focus only on the mkdocs binary itself, not on plugins that still work under mkdocs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants