Hello 👋,

I've teased this post in multiple discussions, and I finally thought it's the right time to write about my work at Nype, which hired me after noticing some of my unsolicited advice on the forums, as they were looking into some ways how to extend their MkDocs websites with the Material theme.

You could say I'm one of the success stories, where one contributes on forums for long enough to get some gig work by chance.🥳

At first, my tasks centred around providing general support for issues concerning extra CSS / JavaScript or I had to write some hooks, which either fixed or extended the functionality of the Material theme or MkDocs itself.

However, over time maintaining the same or similar extra CSS / JavaScript files and updating hooks between multiple repositories started to get quite tedious and partially more error prone, as the chance of me forgetting to update a file in one of these repositories grew.

Hence, I've suggested to put every customization into a separate theme Python package, as this way, there would only be a single source for the changes.

Nype's theme for MkDocs

Therefore, the mkdocs-nype theme package got created, and it covers a wide range of different changes one could introduce to extend the Material theme or MkDocs itself.

It's not a competing project to the Material theme, as it wouldn't exist without it. For now it's also considered Alpha/Beta version for the public audience, as it mainly focuses on Nype's needs and could have breaking changes at any time in the future. Therefore, I post it here as more of a reference for extensions. In similar fashion like McDic did in their post here. Also a lot of the initial hooks that got ported over to plugins, lack the typical configuration that plugins allow, as the hooks were made with a specific setup in mind.

When making the theme I wanted the transition to be somewhat seamless, minimising the impact on the mkdocs.yml re-configuration for the same functionality. Switching from material to nype caused the scope of the loaded plugins to change. There was no nype/blog plugin to load, and I didn't want to enforce the change to explicitly load material/blog inside mkdocs.yml, so I've added a hack to the package __init__.py file to add material as a fallback scope. This was possible, because that file is the entry point of the theme, and the theme import executes before the logic for plugin loading.

Hopefully, this hacky example gets the gist of the new theme's spirit across. There are a lot of hacks in action, which could prevent from updating to the newest MkDocs or Material version, but for now there was no new minor/major release since almost a year, so I would say the API is pretty stable for both of these projects 👀🤞.

On the Reference page I've written more about all kinds of non-standard customizations and hacks.

But the general idea is, We Got All The Hacks.😁

Here, I will point out a bit more of the visuals.
Thanks to multiple customizations including:

• extending the BlogConfig,
• adding custom templates,
• adding a plugin which injects SAP icons,
• borrowing some CSS from this theme's home page,

It was possible to add a configurable custom flavour of the blog index pages, which work well for listing out categories with their posts on a single page. You can see it in action on the Fiori Tracker Use Cases page.

Plugins

The Nype theme was built on top of the community version of the Material theme, and each plugin tries to cover a specific business use case.

• How to show related posts on the blog?

  The Similar Blog Posts plugin allowed to automatically add a list of similar blog posts at the bottom of each article. The similarity is calculated based on the number of matching categories. An example can be seen here.

• How to embed a list of blog posts on the home page?

  The Latest Blog Posts plugin allowed to display last posts from a blog on the home page. However, due to it being a hook initially, the configuration is managed in the index.md file with a placeholder instead of a proper mkdocs.yml plugin config. An example can be seen on the Nype website.

• How to add icons specific to our business niche?

  The SAP Icons allowed to extend the micrographics language of the websites. The plugin downloads an index of public SAP icons and then extends the loading logic of Jinja2 to intercept the calls to the filesystem looking for an SVG file and instead it provides the data from the index. The icons were also made available in the emoji extension. An example with the SAP logo from the external icon pack, can be seen in the Fiori Tracker Benefits section.

• How to group blog posts together other than assigning categories?

  The Custom Blog Categorization plugin allowed to add another layer of categorizing posts in a blog. By default plain Categories, Archive dates, and Authors were available. With this plugin you can add another way like business Industries the Nype company has experience with.

Afterword

Thanks a lot for reading my post. I hope this was worth your time and that it has properly shown the possibilities of monkey patching ✌

I think that these extensions were worth pointing out here as they deliver a direct visual change to the page. Of course there are various backend changes as well you might be interested in.

To bridge the gap between the theme, plugins and templates, I added the Nype Tweaks plugin which handles a lot of different changes that are too small for their own plugin. For example it injects a theme macros path to the MkDocs runtime, so macros templates can be reused across different projects, like the form on the contact page.

Even though the quality of the solutions isn't constant, I'm still happy with each one of them, as I learned some tricks along the way, and I got better at hacking MkDocs over time. 😄

Lastly, I would like to thank @squidfunk for creating the Material theme, and in turn, also created this opportunity for me 🥹🙏