Building a custom theme on top of material?

[FredZinelli]

Hello,

First and foremost, thank you for this extensive effort. Material is truly a fantastic tool!

I'm reaching out for guidance in a particular context. To provide some background, I am a state worker teacher in France, and along with some colleagues, we have developed a website by heavily customizing mkdocs and mkdocs-material. The entire project is under a non-commercial license (note: the associated repository is not public, for now).
I am currently working on creating a custom theme to make it easier for my colleagues to integrate the underlying "machinery" in their own websites. The aim is for them to be able to simply do pip install custom-theme and obtain all the necessary features. However, to achieve this, I would need to create a theme that inherits from Material.

So, first things first: is this acceptable to you? I believe the license is compatible (note: as you can see, the reference to Material is still in the footer, and it will remain there by default).

Assuming it is acceptable, here's what led me to you:
I have been searching for information on packaging a mkdocs theme that itself uses another theme, but I haven't found anything yet. Currently, my only idea is to build my package by initially copying the files from the material package directory, then constructing around that and packaging the result. However, this approach feels incredibly messy and impractical... and it even seems somewhat disrespectful towards Material. I suspect I'm overlooking something... So, what would be the appropriate method for accomplishing this? I'm hoping for something along the lines of inherit: material in the theme_mkdocs.yml or a similar concept, if possible.

Thank you in advance.

Kind regards,
Fred

EDIT: I just saw extends: mkdocs in some mkdocs example repo. So is that it? Just extends: material in the theme_mkdocs.yml and I'm good to go?

[kamilkrzyskow]

Hello @FredZinelli,
the extends setting should be what you're looking for as it's documented here and has the description you're looking for
https://www.mkdocs.org/dev-guide/themes/#theme-configuration

Never really tried it but it should work, just remember that your theme dependencies need to install the material theme as well, as it won't be fetched based on this setting alone.

[FredZinelli]

Damn it, I didn't see the info in that page...
Deps: sure thing, thanks a lot for the heads up.

Since you didn't talk about the license, I guess that means it' also ok? If so, no need to answer! (...in an attempt to reduce the amount of noisy notifications... I probably should have asked directly on mkdocs. Sorry about that...)

Thanks again!

[kamilkrzyskow]

I'm not really a maintainer, so perhaps not the best person to answer @squidfunk should make a comment.

The licence for the Community version is MIT so there should be no problem, especially since you're planning to still attribute the theme at the bottom.

[squidfunk]

Material for MkDocs is licensed under MIT, so as long a you abide to the license, it's all fine by me ☺️ The license says:

Copyright © 2016-2024 Martin Donath

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

[...]

Thus, as long as you attribute us, all good!

[FredZinelli]

Hello,

Quick feedback: I'm currently using extends: material in mkdocs_theme.yml successfully, but I ran into an unexpected problem about material plugins. It seems I have a work around (though I'm not sure everything is fully functional yet), so I'm not sure it's worth exploring this on your side but I thought you could be interested and/or could give me some thoughts about it.
So, here is the thing:

• The entry points for material plugins are registered with material/{plugin_name}.
• With my personnal theme extending material, I got an error about the tags plugin not being installed while running mkdocs serve even though the plugin is registered in mkdocs.yml (note: I didn't try with other plugins, that's why I only talk about that one)
• Everything works fine when I use material as theme instead of mine.
• I could make the plugin "visible again" (I'm not sure everything is working yet) with my personal theme by registering new entry points for material plugins in my package, removing the material/ prefixes.

All this seems very weird. Especially, I don't really get how material plugins are seen in mkdocs with their current entry points when using material itself, and not anymore when extending the material theme...
Anyway, I just wanted to let you know. If ever something isn't actually working, I'll come back to you. And if ever something comes to your mind about that, please let me know.

Kind regards,
Fred

[kamilkrzyskow]

That's the expected behaviour, https://www.mkdocs.org/about/release-notes/#version-141-2022-10-15
The plugins use the material/name plugin entries to detect them in templates etc., I'm not sure if changing the entry points won't lead to issues hmm. Best course of action would be to use the proper entries in the plugins section with the prefixed material, or make sure that each material/ plugin entry in templates etc. are also changed to your changed entry points.

EDIT: For example the search:

mkdocs-material/src/templates/partials/header.html

Lines 92 to 101 in 7d6d8d7

	<!-- Button to open search modal -->
	{% if "material/search" in config.plugins %}
	<label class="md-header__button md-icon" for="__search">
	{% set icon = config.theme.icon.search or "material/magnify" %}
	{% include ".icons/" ~ icon ~ ".svg" %}
	</label>
	<!-- Search interface -->
	{% include "partials/search.html" %}
	{% endif %}

[FredZinelli]

Yes, exactly. I just finished to update what needed to be and saw the search bar didn't work anymore, effectively.
Ok, I just tried filling the mkdocs.yml with - material/search and it perfectly does the trick.

Thanks again!

👍