An attempt at mimicking the pydata-sphinx-theme in MkDocs

[jorenham]

I needed some documentation for numpy/numtype, but I have no experience with sphinx; only markdown; so we decided to go with MkDocs.

But the default theme was hurting my eyes, and I found myself longing for the comfort of the pydata-sphinx-theme. So with barely any graphical design experience, as well as colorblindness, I decided it would be a great idea to try to port mimick the pydata-sphinx-theme in MkDocs Material.

Now it's online for the whole world to see (https://numpy.org/numtype/). So I thought I'd share it here, in the hope that you might be able to tell me how much I butchered it, or better yet, how to "un-butcher" it. And of course, PR's are very welcome :)

[AA-Turner]

Out of curiosity, what were the drawbacks with Sphinx's support for markdown (via MyST) that led you to choose MkDocs? Note e.g. that much of this theme's documentation is written in markdown. I'd be grateful for feedback on how we can improve either our user experience or our advertising!

A

[jorenham]

The main reason is that I have experience with mkdocs, and was (and still am) satisfied with its ease of setup. But to be honest, I wasn't aware of MyST. But even if I were, I don't think that would have affected my choice. Because at first glance, setting it up looks quite a bit more involved. It's probably the more flexible choice, but for this purpose, that additional flexibility would probably not be needed.

[trallard]

Hey, @jorenham, thanks for sharing!

So I thought I'd share it here, in the hope that you might be able to tell me how much I butchered it, or better yet, how to "un-butcher" it. And of course, PR's are very welcome :)

This is fairly new and only scoped for some components, so I cannot give much detailed feedback.
Though I noticed the primary and secondary colours are different from those in PST, I am unsure if this was intentional or an oversight.
Anyway, I wanted to point out the following resources that might be helpful as you continue to refine the theme:

• PyData Sphinx Theme design documentation: is our top-level design documentation, rationale and approach to design. This also links the relevant files where we define our colour variables.
• Community Figma file: there you will find all the colours, interactions, and other details.

Happy to help if needed.

[jorenham]

Though I noticed the primary and secondary colours are different from those in PST, I am unsure if this was intentional or an oversight.

Hmm I guess I must've overridden the wrong css variables or copied the wrong color codes. I noticed in the css several primary color codes (on both sides), and I wasn't which one I should use. The secondary I wasn't able to find at all in mkdocs, so I'm not sure how to translate that.

• PyData Sphinx Theme design documentation: is our top-level design documentation, rationale and approach to design. This also links the relevant files where we define our colour variables.
• Community Figma file: there you will find all the colours, interactions, and other details.

Yea I spotted the figma file earlier, but somehow missed the docs; thanks for sharing! But as far as I can tell it looks all pretty high level, and I'm not sure how to translate that into something concrete that I can apply here 🤔.

Happy to help if needed.
That would certainly be appreciated!
The customizations I've made so far can be found in docs/style/theme.css. There I've also copied over any of the relevant theme colors I could find, mostly for reference. There's also some higher-level theme options in mkdocs.yml, but I believe that most of those can also be overridden from css. Feel free to fiddle around with it if you want to.

[jorenham]

I've made some progress, and this is what it looks like now:

For the headers I went a bit off-piste, and went with the Lato font, matching the NumPy logo. If that's not a good idea, feel free to let me know.

I didn't look into pygments yet, so the code blocks look rather out-of-tune. But I feel like the other content is getting pretty close to how it should be now.