Mkdocs-material: Macros plugin

[ajcollett]

__I checked that...__

• [x] ... the documentation does not mention anything about my idea
• [x] ... to my best knowledge, my idea wouldn't break something for other users
• [x] ... there are no open or closed issues that are related to my idea

Description

I found this plugin recently: https://github.com/fralau/mkdocs_macros_plugin

I know it's supported, but not in the docker image.

My question is, why is it not in? Is it just new? Or is there a fundamental reason to avoid it? If no, might it be worth adding?

More importantly, is there any reason this Plugin will not work with MKdocs Material?

Use Cases

It would be great to be able to define variables and macros that one can then use all over the documentation. I know there are some plugins already that support some form of snippet or variables, but this seems to be the "one ring to rule them all"?

Specifically, I had a table to create, with a bunch of links to the same website, but with different parameters and paths. The table becomes unwieldy to edit, if say something like the server URL changes. With macros, that would be quite a lot easier.

[facelessuser]

The answer is probably more simple than that. The docker image is not meant to contain every possible mkdocs plugin. @squidfunk has included the ones he's deemed most useful. If requirements are needed outside of that, you'd probably have to roll your own or not use the docker image. To be fair, I never use the docker image and have no problem pushing my documents 🤷.

[squidfunk]

In the end, there are thousands of MkDocs plugins out there. We try to strike a balance not blowing the image up too much by installing all of them and providing meaningful defaults. If this is useful to more people, we can integrate it. However, note that it's very simple to extend the Docker image to install your own extensions:

FROM squidfunk/mkdocs-material
RUN pip install mkdocs-macros-plugin

That should be about it.

[ajcollett]

Thanks for the feedback.

I have quite a few pipelines that make use of the MKDocs Material image, one of which I have done exactly that (what @squidfunk mentioned). It's a little more complex, since it's to create a PDF of the site as well as well as the site, but same idea. Roll your own.

However, where I can I try stick with the provided image, since it's one less thing to maintain (I have lots of sys admin tasks :-P).

I was also thinking this might be really helpful to lots of people. Thus to maybe integrate it.

However, since the plugin has existed for a while, and no one else has mentioned it, maybe the want/need for it to be built in isn't great. In which case, I think I'll close this. If others come along in the future, maybe this can be the "first port of call" issue?

Thanks for the replies, I think it's right not to bloat the image with plugins that only get used by a hand full of people.

Also, thanks for the awesome software. :smile:

[squidfunk]

Funnily, I just had a conversation with a client about injecting custom data into Markdown, so I think your plugin is very useful. Would you like to add it to the reference? You can draft a PR for a new docs page to promote your plugin on the official docs, if you like. I think it would be a great addition.

EDIT: sorry, I thought you wrote the plugin, I misread. Anyway, if @fralau wants to jump he may create a PR 😉

[fralau]

@squidfunk All right, let me know what it is exactly you are expecting from me, and I will try to oblige 🙂 . My knowledge of docker is limited, so I'd be happy to have a few pointers.

[squidfunk]

@fralau my idea was to document your plugin in the reference section, similar to the other references 😊 if more people need it, we can eventually include it in the Docker image.

[fralau]

@squidfunk Sure: documentation is something I know I can do 😊 .

[fralau]

Shall we reopen this issue, or should I create a new issue?

[squidfunk]

Just create a PR when you have a first draft.