Replies: 7 comments 19 replies
-
I am reaching out to a designer friend of mine to see if they might be interested in contributing to this project. If others have friends who are designers, I encourage you to approach them as well. I was going to bed last night thinking about this... I have a slight bias towards building a new theme to power mkdocs, only because I think it would be beneficial to the product if we could relaunch with two awesome themes as opposed to only one. Wearing my marketer's hat I envisioned a mkdocs website that was (in a way) like a love letter to markdown. I fixated on the idea that one thing I bet everyone here has in common is a love for markdown. So I thought of a mkdocs website that celebrates markdown, and introduces people to a pretty powerful idea: how one could implement an entire website using nothing but text and markdown. I see a website with messaging that is effective at igniting people's passion around the values that bring us to this project (markdown, code-as-documentation, SSG, and so forth). I see amazing documentation, and a plugin and theme gallery. I see a blog, and other support resources. That being said, if we don't have resources, time or expertise to develop such a theme, then we shouldn't. Material is the next logical choice, and I see only upside in adopting it. We might only be talking about using material for the mkdocs website. But if we are talking about bundling a version of material with mkdocs out-of-the-box, then I would love to engage in a dialog with @squidfunk about how we could complement his business model. For example, could mkdocs bundle a super-simplified version of Material for free, and then help upsell people to "Material Premium." Or something. |
Beta Was this translation helpful? Give feedback.
-
Thanks @pawamoy My feeling is that MkDocs with a new theme and documentation would be in a great position, especially with Material for MkDocs alongside. I'd certainly enjoy working on that and can probably make a decent amount of time for it.
Yep, I'm invested in us pushing for getting some funding behind (One way or another I would like to capitalise on the project's success in a way that'd allow me to spend time on it again.) |
Beta Was this translation helpful? Give feedback.
-
My opinion: Material is the right choice that currently brings a maximum amount of functionality and beauty to the table. But it is a bit boring seeing most documentation pages being built that way, only varying slightly in color (but also: this is fine for documentation pages! They should just work and be functional). Yes, the MkDocs page is a documentation about features of a software, but it's also a project and an ecosystem. How can this page stand out or rather differ itself from the material homepage (which does a perfect job at documenting all its features). The least we should do is mod the sh*t out of material to show what can be done to make it look different (but I currently have no clue how to achieve this...). Maybe someone knows an artist who is willing (or getting paid via funding) to contribute a painting/picture for the front page of the home page (mh... again assimilating the material page, but we'll find a way to make it different...) |
Beta Was this translation helpful? Give feedback.
-
I think it is worth the effort to try and recruit a designer to help design a new default theme. It is a longshot asking people to give their time like that, but it can't hurt to ask. I am reaching out to a few people I know. I'd like to encourage others to do the same. |
Beta Was this translation helpful? Give feedback.
-
Ok, upcoming work seems to be shaping up :) IIUC @tomchristie and @byrnereese seem to want to work on a new theme: that's great! I won't be able to help on the new theme (I'm already bad enough at designing the few aspects of mkdocstrings xD), but don't hesitate to tag me if you feel I can contribute. In the meantime I'll focus my efforts on the catalog: we can start including a theme/plugin gallery before switching to a new theme. |
Beta Was this translation helpful? Give feedback.
-
One thing we should contemplate is what kind of visual/textual constructs should our default theme support? For example, here are some of the syntaxes I love from the Material theme that I would love to see supported in our default theme:
Here are some of the features of the Material theme I would love to support in our default theme:
I should have started with this, but my criteria for the above is based on an unstated goal: our default theme should empower writers to create compelling documentation (with effective and commonly used messaging constructs), and to be able to easily differentiate their site from other mkdocs-powered sites. One model I love can be found in Bootstrap and the examples they provide (granted, this is not a perfect corollary, but bear with me): What I would like to showcase are many different variations of what a site can look like using mkdocs default theme. For example, I think it would be super useful if people who browse a library of screenshots depicting different permutations of a mkdocs site powered by the features above. When I find the design/layout I want, I download the mkdocs.yml for that configuration, and I just start writing. In the end, the power I think we can deliver is all about customizability and variability. Help companies create a site that more reliably and closely extends their brand. You know? |
Beta Was this translation helpful? Give feedback.
-
Replying to OP post (So excuse if that stuff was already decided), I dislike the use of a different theme for the MkDocs site. At least one that isn't available within MkDocs directly. If a user visits the site and decides to use it because of the nice looking theme, they will be rather disappointed when installing and running it, only to see a different theme, not matching the one of the site. The site should represent MkDocs itself. Its features and its design. So having a different theme that isn't part of default MkDocs would destroy this purpose by basically lieing to the people. |
Beta Was this translation helpful? Give feedback.
-
In this discussion I'd like to chat about whether we should use a different theme for MkDocs documentation itself. Several members seem to favor using Material for MkDocs (I do myself).
Some would prefer to create a new theme, to use it as default and maybe for MkDocs too: https://github.com/mkdocs/mkdocs-team-space/discussions/4. However I don't think anyone currently has the will, time and skill to create a new theme, or at least it won't happen soon.
So, I consider more urgent to decide if we should change the theme used at https://www.mkdocs.org/. The website is the entry-point for many new users, and we would gain at making it very convincing that MkDocs is a fantastic tool.
@squidfunk has offered his help to migrate to Material for MkDocs if we decide to use it. I suppose minimal changes are required in the docs themselves, such as clearly explaining that the theme used is
X
but by default MkDocs usesmkdocs
. Other than that I don't think we need changes. Other improvements can be done in subsequent work, iteratively.WDYT 🙂? Should we have a poll with existing themes?
Beta Was this translation helpful? Give feedback.
All reactions