Theme for MkDocs' own docs

[pawamoy]

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 uses mkdocs. 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?

[byrnereese]

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.

[squidfunk]

You're describing the exact value proposition of Material for MkDocs: documentation that simply works, that is beautiful, that you can generate without any web development knowledge and entirely from Markdown. If MkDocs would adopt the same ethos – awesome, even better. It has been my motivation and driving force all along.

On another note, I'm happy to help to migrate to Material for MkDocs, if a consensus is reached that this is desired, but I would not want MkDocs itself to upsell to our Insiders version. That would just not feel right.

[tomchristie]

WDYT

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.

how we could complement his business model

Yep, I'm invested in us pushing for getting some funding behind mkdocs. I've been doing that with @encode for a while, and we've got a fair bit of traction. I can also say that I'd consider bringing mkdocs into the encode fold if I felt there was a good way to unify all of those projects documentation styles, sponsorship placements, communication, and project management.

(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.)

[unverbuggt]

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...)

[squidfunk]

Thanks for your input! I can confirm that most users just use the defaults of Material for MkDocs, but this is actually true for almost all themes. Before there was Material for MkDocs, everything looked like ReadTheDocs, so I guess it is the curse of popularity 😅 We plan to put more focus on how to mod Material for MkDocs in our own documentation in the future.

---

I skimmed through the MkDocs documentation, and there would at least be some parts of it what would either need explanation or rewriting, especially the getting started guide, as it contains a lot of screenshots: https://www.mkdocs.org/getting-started/

If Material for MkDocs would be used, these screenshots would now not match the current appearance of the page, which could be confusing, and which might also be true for other parts. Thus, the documentation will need to be redone or even rethought. I believe that "just switching to Material for MkDocs" might not be possible – it will be quite an effort. As offered, I can assist on the theme migration, but please understand that I'm not able to help out on the documentation rewriting – I'm already going through another rewrite of our own documentation right now 😅

Honestly, the more I think about it and contemplate on mkdocs/mkdocs-team-space#4, the less I believe that switching to Material for MkDocs is a viable and good idea for the necessary effort and problems that it will entail. A new or revamped default theme might be a better option, because it would mean less explanation is necessary. Additionally, it'll have a better user experience from the start.

[byrnereese]

@squidfunk You have expressed several times a concern for the level of effort associated with switching to Material for mkdocs. Can you elucidate where the complexity lies in this effort? I think some of us with less experience with Material think it will be "easy." So I am curious to learn what we don't yet understand. :)

[squidfunk]

Of course. Here are the problems I see with getting a new user up and running:

• Option 1: Only making use of Material for MkDocs to build MkDocs' own documentation, we'd need to decide what happens with the bundled themes (mkdocs and readthedocs), as the user experience for a new user that installs MkDocs would be confusing. MkDocs own docs are built with Material for MkDocs, but the user runs mkdocs serve and sees the mkdocs theme. IMHO this is not a good user experience.

• Option 2: Making Material for MkDocs the default theme would be another option, but that would mean Material for MkDocs would always need to be installed alongside MkDocs. Since Material for MkDocs has a dependency on MkDocs, we would create a cyclic dependency – not good. I'm not sure we can remove the dependency of Material for MkDocs on MkDocs, because we need to specify precisely with which versions of MkDocs Material for MkDocs and all of its plugin are compatible.

• Option 3: Making theme installation mandatory. If the mkdocs and readthedocs theme are moved out of core, theme installation could be made mandatory. For instance, since MkDocs is a dependency of Material for MkDocs, you only need to install mkdocs-material and a compatible version of mkdocs will be installed automatically. Moving themes out of core, the installation target could be moved downstream to the themes, e.g., which might be called mkdocs-classic (suggested by @tomchristie) and mkdocs-readthedocs. This would however mean that installing only mkdocs will not get you any theme, which might not be what users expect. Again, this would need to be clarified in the documentation, and it might make the setup process more complicated.

As mentioned before, the MkDocs documentation contains a lot of screenshots, which might need to be redone given what option is chosen. Additionally, just switching the theme to Material, you're not getting the best out of it, so the documentation might need a restructuring as well. Last, if the use of Material for MkDocs should only be temporary until a new default theme is available, we'd need to specify what features of Material for MkDocs to use, because they would either need to be ported to the default theme or removed once the switch to another theme occurs (downward compatibility).

It depends on what @tomchristie has in mind for MkDocs, as he mentioned that he's going to take the lead on MkDocs again. Any of these options might be viable, but IMHO, it should be tackled with great care, or MkDocs' popularity might plummet when it is made more complicated.

With Material for MkDocs, we try to make it as simple as we possibly can to get started, which is a major factor for its success.

[byrnereese]

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.

[byrnereese]

Does anyone have connections with the markdown community? Is there a "markdown community?"

I reached out to John Gruber to see if he has advice for us. :)

[byrnereese]

FYI - here is the email and response I received from John Gruber.

John,

Hey - quick intro: my name is Byrne Reese. Our paths may have crossed paths briefly when I worked at Six Apart with Anil Dash, Ben and Mena, Andrew Anker, Michael Sippey, Brad Fitz and others. I was the PM for TypePad and Moveable Type.

In any event, I wanted to ask your advice quickly. I recently began to contribute my time to an open source project that I adore called mkdocs. It is a markdown-centric SSG and publishing system. The project has been growing in popularity and we wanted to take it to the next level. The project is in need of a designer who might be interested in contributing their time to a redesign of the project's website for mkdocs. The design would also become the new default theme of the project.

I want the design to be a love letter to markdown - as that is what every member of this project has in common: a real love and respect for markdown.

I wanted to see if you might have some advice for us with regards to any people or communities we might be able to approach with this opportunity.

Byrne

PS. I am also curious - have you heard of the project? The project has really started to take off due to this great theme and website framework: https://squidfunk.github.io/mkdocs-material/

---

His response:

Hey - quick intro: my name is Byrne Reese. Our paths may have crossed paths briefly when I worked at Six Apart with Anil Dash, Ben and Mena, Andrew Anker, Michael Sippey, Brad Fitz and others. I was the PM for TypePad and Moveable Type.

I remember your name well! Delighted to hear from you.

In any event, I wanted to ask your advice quickly. I recently began to contribute my time to an open source project that I adore called mkdocs. It is a markdown-centric SSG and publishing system. The project has been growing in popularity and we wanted to take it to the next level. The project is in need of a designer who might be interested in contributing their time to a redesign of the project's website for mkdocs. The design would also become the new default theme of the project.

That’s very flattering to hear. I’m not one for celebrating my own milestones — barely acknowledged DF’s own 20th anniversary (this was all I wrote: https://daringfireball.net/linked/2022/08/13/20) and I let Markdown’s 20th pass un-remarked-upon last month. But still: 20!

I actually do mean to write some retrospective Markdown stuff soon, including pointing out what I consider to be my syntax mistakes. If I had my shit together that would’ve happened last month.

I wanted to see if you might have some advice for us with regards to any people or communities we might be able to approach with this opportunity.

I don’t have any suggestions for this but I’d be happy to offer feedback personally, perhaps?

PS. I am also curious - have you heard of the project? The project has really started to take off due to this great theme and website framework: https://squidfunk.github.io/mkdocs-material/

No, I had not — looking at it now!

—J.G.

---

I will continue to correspond with him to see what more I can learn - and hopefully get his help in promoting mkdocs once we relaunch. There are some marketing opportunities to recruit a list of advisors for the project, and see if he would lend his name ot the list.

[tomchristie]

That's delightful, thanks so much Byrne. ☺️

[pawamoy]

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'll up the relevant discussion priority and remove the one from here, as theming MkDocs will depend on developing a new theme.

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.

[byrnereese]

@timvink You are right - it is non-trivial. That is a problem I think markdown could conceivably help solve though. The trick in a sense is to abstract the writer away from HTML and CSS. Markdown is perfectly well-suited to that task. We just need to provide the syntax to create HTML elements from text. I want to make that a much easier process if possible.

For any kind of short-term needs - we may just need to enlist the help of a designer to create a more visual homepage for us.

(but just so I am clear and do not miscommunicate - that is not a priority in the short-term)

[koaning]

I also use mkdocs on my own site https://koaning.io/ and I think I've had the same experience as @timvink.

[byrnereese]

@timvink @koaning These are AWESOME sites and examples of what people can build. I really want to make this a part of the mkdocs story.

I think we can learn a lot from the early days of Wordpress, which was able to propel itself into a dominant position because it had the most robust and diverse collection of themes available. I want to do the same for mkdocs.

[squidfunk]

I used mkdocs for my own website, and found the creation of a more visual homepage non-trivial. Here's the home.html override I used, which might help. Unfortunately I don't have the frontend skills to help out here..

@timvink You are right - it is non-trivial. That is a problem I think markdown could conceivably help solve though. The trick in a sense is to abstract the writer away from HTML and CSS. Markdown is perfectly well-suited to that task. We just need to provide the syntax to create HTML elements from text. I want to make that a much easier process if possible.

This is the insanely tricky part. I have thought long, long, and long about how we can make creating non-linear pages easy and I have not yet reached a final conclusion. The correspondence of: "one file, one content area, one page" doesn't lend itself well to creating a page with multiple sections, where each section has multiple boxes with repeated structures, e.g.:

• Our features
• Our testimonials
• ...

If somebody cooks up a good solution for this that does not mandate the author to either use custom templates (our current solution) or copy and paste big piles of HTML into Markdown (which is very error prone), we'd switch to it in a second. I'll continue to think about this problem and hope to find a solution quickly, because I want to empower users to build landing pages more easily. If somebody finds a solution here, I'll send a big bucket of flowers!

[waylan]

That is a problem I think markdown could conceivably help solve though.

You might want to check out Bootstrap4Markdown, which is an experimental Markdown extension built on top of the Blocks extension of pymdown-extensions. Using a simple syntax, one can include complex Bootstrap objects in a Markdown document. The extension is currently incomplete and only supports a few object types, but it demonstrates what can be done with Blocks. As the existing mkdocs theme is based on Bootstrap, the extension could be used as-is on any site which uses that theme. A similar extension could easily be created for any other CSS framework.

[byrnereese]

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:

• Admonitions
• Buttons
• Code blocks
• Grids
• Icons, emojis
• Tables
• Tabs

Here are some of the features of the Material theme I would love to support in our default theme:

• Navigation tabs
• Navigation sections
• Navigation expansion
• Social cards
• Announcement bar
• Site favicon and logos
• Font support
• Site colors

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):
https://getbootstrap.com/docs/5.3/examples/

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?

[squidfunk]

Great idea! By the way, when writing plugins for Material for MkDocs, I aim to make them compatible with all other themes. For instance, I just pushed a tiny fix that makes the social plugin perfectly workable with the mkdocs theme: social-cards.zip

pip install mkdocs "mkdocs-material[imaging]"

Extracting the zip and running the project then results in:

The configuration is simple:

site_name: MkDocs
site_description: Project documentation with Markdown
theme:
  name: mkdocs
  logo: mkdocs.png
plugins:
  - material/social:
      cards_layout_options:
        background_color: "#2FA4E7"

I'm just raising this as a possible fast path – I have no upside of any of this, au contraire: we commit to the plugins being compatible with other themes, which is more work for us that we're happy to take on in order to strengthen the ecosystem.

[squidfunk]

Addendum: now also works with Insiders and its alternate and custom layouts ☺️

If there are compatibility issues in other plugins that we ship as part of Material for MkDocs, e.g. the privacy or optimize plugin, which should work perfectly, please raise an issue. We're happy to make them compatible, albeit they should already be.

[Andre601]

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.

[squidfunk]

I agree, except for the lying part – it can be explained. Switching to Material for MkDocs was originally not brought up by me, but by several other users. I only tried to help discuss what it would entail, and eventually came to the conclusion that is might not be a good idea after all, more specifically and with detailed explanations in #3661 (reply in thread) and #3661 (reply in thread)