How do I create an extension and use it with markdown_extensions

[karl-police]

The docs of Python Markdown and etc. don't help me.

I don't even know how I can load the extension

I assume I need to use markdown_extensions: and put something in there, but I don't even know what to put in there

 

I tried reading the docs, but I skipped everything that didn't contain markdown_extensions

I have no clue how this works, so let's say I wanna write an extension, and put it inside docs/extensions/myExtension.py

what do I type in markdown_extensions: to load it?

I do not know which repository is even right for this question because markdown_extensions is something from mkdocs, but mkdocs-material is more advanced and idk

[alexvoss]

It might help us if you said what it is you want to achieve. Writing an extension for Python Markdown is likely not a trivial exercise, so best to check if that is even necessary.

[karl-police]

a simple thing, apparently I need Preprocessor

I only wanted to replace tags like

<args>
    <arg name="arg1" type="string">Description</arg>
    <arg name="arg2" type="string">Description</arg>
</args>

with something else and parse through its stuff and then replace it with like custom <div> and HTML stuff

that's about it

[alexvoss]

Not sure I understand. What is a 'tag' in this?

If you need to match something in the Markdown source then a hook that attaches to the on_page_markdown event should do the job. You can change the Markdown code before it gets converted to HTML.

[kamilkrzyskow]

IMO this is more of a MkDocs discussion board question, since it is a configuration option of theirs:
https://www.mkdocs.org/user-guide/configuration/#markdown_extensions
As said in the description it uses the Python Markdown library to process markdown, and this library offers an extension system:
https://python-markdown.github.io/extensions/
Additionally Material for MkDocs uses a custom set of extensions provided by the PyMdown Extensions library:
https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/
You should be able to look there for an example how to write such extensions. On first look I don't see anything related to the install process of the plugin, nothing attaches to any entry points. I'll report if I'll find how it gets connected 🤔

[karl-police]

yeah, my issue is I can't figure out how it is all connected :/

[kamilkrzyskow]

Looking at https://facelessuser.github.io/pymdown-extensions/extensions/emoji/ I understand that as the usage in base Python is

import markdown
md = markdown.Markdown(extensions=['pymdownx.emoji'])

then I assume that once you use the pymdownx.emoji inside the markdown_extensions then MkDocs will import pymdownx.emoji and simply use it via the makeExtension function 🤔

Not so simple, I checked deeper and MkDocs registers the extension via the
https://python-markdown.github.io/extensions/api/#registerextension function
https://github.com/mkdocs/mkdocs/blob/646987da4502becf346bfaabb6ba40934307399b/mkdocs/config/config_options.py#L1031
which in turn calls Markdown.build_extension, which in turn imports the module and calls the module.makeExtension function.
https://github.com/Python-Markdown/markdown/blob/cef5afeb959d11e1ad5566fefa1f9a71136c1050/markdown/core.py#L224-L246

[karl-police]

mkdocs/mkdocs#3491 (comment)