Plugin development

[PLAYG0N]

Hello Everyone

Context:
I am currently working on my first plugin.
In the end my plugin should modify the HTML code and add more functionality.

I've seen a lot of plugins which have icons (as svg) in the resulting HTML. But I couldn't figure out how they added these to the HTML.

Is there a standardized way of which I am not aware of?

Are there any other resources for plugin development?

So far I've found :

• MkDocs Documentation
• Template
• Guide by Sam

[kamilkrzyskow]

Hello @PLAYG0N,

Is there a standardized way of which I am not aware of?

I'm not sure if I understood the scope of this question correctly, but plugins in MkDocs should follow the event execution loop:

• https://www.mkdocs.org/dev-guide/plugins/#events
  Open up the diagram to see the flow of the loop.

I didn't read Guide by Sam, but after a skim it seems to be a good introduction to the topic, but personally I would just copy a simple plugin, manually, file-by-file, and learn it this way, fixing bugs along the way ✌️ I'm not sure if you're a beginner to Python, if so, you could use these resources for a better understanding of the basics in general:

• https://cs50.harvard.edu/python/2022/
• https://www.youtube.com/watch?v=DhUpxWjOhME EDIT: I've skimmed through this video about project setup, and it's a bit outdated as well... as most of the configuration can be accessed from the pyproject.toml file, just like with the example of this repository:
  • https://github.com/squidfunk/mkdocs-material/blob/master/pyproject.toml
  • I can't think of a better resource alternative for project setup right now...

The Template is a bit outdated, as it doesn't introduce the PluginConfig approach:

• https://www.mkdocs.org/dev-guide/plugins/#subclassing-config-to-specify-the-config-schema

Note

You could consider making a Markdown Extension to process the tokenized strings instead of relying on regex replacement in events and improve performance, but I never done it myself, so can't point to any direction. If your project is small or a one-off you probably shouldn't worry about performance, just focus on the simplest solution first 👌

---

As for plugins a short rundown to perhaps add to or repeat things from your other resources:

To edit Markdown before it's rendered with Markdown Extensions you'd use on_page_markdown:

• https://www.mkdocs.org/dev-guide/plugins/#on_page_markdown
  You can inject HTML in that step as well, and make use of the md_in_html extension to combine both Markdown and HTML:
  • https://python-markdown.github.io/extensions/md_in_html/

---

If you need to modify HTML after it's been processed by the Markdown processor then you'd use on_page_content:

• https://www.mkdocs.org/dev-guide/plugins/#on_page_content
  But as the name implies you have access only to the content rendered from Markdown in this event.

---

If you need to modify other HTML outside of the Markdown content, then you'd use on_post_page:

• https://www.mkdocs.org/dev-guide/plugins/#on_post_page

---

If this is a one-off for your project then consider to make a hook instead of a plugin:

• https://www.mkdocs.org/user-guide/configuration/#hooks

One example could be the hook used in this documentation to inject Convention icons:

• https://squidfunk.github.io/mkdocs-material/conventions/
• https://github.com/squidfunk/mkdocs-material/blob/master/src/overrides/hooks/shortcodes.py

[PLAYG0N]

Thanks a lot this helps a ton :)