Use a different MkDocs theme.

[pauloxnet]

I propose to use Material for MkDocs as the theme for the MkDocs-based documentation, to modernize it and increase it accessibility.

[pauloxnet]

Opened a PR #1413

[pauloxnet]

As a library user I often use the documentation of this project and miss several features of a modern theme, for example:

• support for mobile devices
• support for dark and light styles
• automatic adaptation to the style of the operating system
• the presence of a general menu that is always visible
• the presence of a search

Regarding the accessibility of the current documentation, measured with PageSpeed, it is much lower (around 77)

• https://pagespeed.web.dev/analysis/https-python-markdown-github-io/2hreapw41q?form_factor=mobile

compared to that measured with the "Material for MkDocs" documentation (around 89)

• https://pagespeed.web.dev/analysis/https-squidfunk-github-io-mkdocs-material-getting-started/l94e1uoqyq?form_factor=mobile

All these and other features are already in "Material for MkDocs" and this is why initially I only inserted a link to its website, because it seems to me much cheaper, in terms of commitment to the project, to adopt that theme instead than to modify the current one.

[facelessuser]

I will state the lack of search is a bug that was introduced very recently. I've created a bug with the identified cause. #1416

[waylan]

@pauloxnet thank you for listing some specific things that you would like to see supported/included in our documentation. I will note that I am very particular about some things and not-so-much about others. Even so, I am not a designer and that is why the current theme mostly borrows its CSS. With that in mind...

• support for mobile devices

A completely reasonable feature. Personally, I don't use mobile devices when referencing documentation, so I have no personal motivation to work on it. However, a solution which supports this would be given serious consideration.

• support for dark and light styles

I suppose. Personally I find dark themes to a usability/accessibility problem. When I am looking at my screen I look at the dark content, and ignore the light colored content (dark text on light background). So when a dark theme is used, I just see blank pages of darkness (because my eyes don't see the light colored text). Obviously, I am an outlier here due to the popularity of dark themes. However, I mention this because I cannot judge a dark theme. When I see one I just start blankly at the page for a couple minutes trying to understand what I'm supposed to even be looking at.

• automatic adaptation to the style of the operating system

If a dark theme is supported at all, absolutely. Then I will never be shown the dark theme. Presumably, some others would feel the same about the light theme??

• the presence of a general menu that is always visible

I'm indifferent to this. Actually, I find Material's global menu to be a usability problem. While working on our API docs I was using mkdocstrings documentation extensively and for the first time finally figured out how that menu works. But I still regularly get lost in the menu (why is the home page not at the outermost level? how do you navigate to an outer level from an inner one?). I like how our current theme works. From any page click on the index link and you get the sitemap which lists all pages. Or use next/previous to move through the documentation in a logical order. I realize that is not the only possible solution, but it is more usable that Material currently is.

• the presence of a search

As noted, this was inadvertently disabled in a recent update and a fix will be made with the next deployment of the docs.

Note that I have altered the title of this issue to better reflect the topic up for discussion.

So, while I am not included to try to develop my own design, I am also not inclined to use the Material theme. And when I look over other MkDocs theme, their templates rarely use best practices. In fact, when we were incorporating mkdocstrings into our documentation, we just used its Material theme because our templates were using best practices (mkdocstrings themes only provide templates, not CSS). The mkdocstrings devs where pleasantly surprised. Therefore, the best solution is likely to involve only minor adjustments to the templates and major changes to or replacement of the CSS. But we need a designer for that.

[facelessuser]

To be fair to the opening request, there are few, well maintained themes that offer great mobile interfaces. I think the reason why many gravitate towards material is that it is very well supported and does implement all of these things.

Personally, I am probably indifferent to the light/dark theme stuff, but the mobile interface is not great with the current theme.

[pawamoy]

why is the home page not at the outermost level? how do you navigate to an outer level from an inner one?

That is bothering me too. I didn't take time yet to look for a solution.

---

Regarding navigation, I find it hard to navigate within the Nature theme, mainly because the left sidebar doesn't show the pages, but only the headings in the current page, and the "next topic". As you mentioned, there's the index link at the top right, but it's not easy to spot, and having to click on index every time you want to see what other pages are available does not help navigation. This could be fixed by showing the index link more prominently, or actually showing pages in the sidebar (maybe not all pages, just the ones at the same level).