Recommend adding a link to the community-supported documentation for publishing to ReadTheDocs

[tleonhardt]

Description

It would be nice to include a link to the official ReadTheDocs documentation to the bottom of the Publishing your site documentation for MkDocs Material along the other community-supported documentation.

Related links

• ReadTheDocs guide for MkDocs Material
• Other section of MkDocs Material Publishing docs
• Source file that needs to change

Proposed change

Edit the - publishing-your-site.md file to contain one additional bullet at the bottom with a link to the ReadTheDocs documentation for publishing MkDocs Material docs there.

Before submitting

• I have read and followed the documentation issue guidelines.
• I have attached the links to the affected sections of the documentation

[niclasheinz]

Hi @tleonhardt

Thanks for your suggestions. I'll check the links and make a PR.

[squidfunk]

Thanks for suggesting! I'm aware of this guide. If you closely read the publishing guide that you linked, you'll realize that it does not include a proper configuration of Material for MkDocs. In fact, the information in this guide is wrong:

Minimal configuration required to build an existing Material for MkDocs project on Read the Docs looks like this, specifying a python toolchain on Ubuntu, defining the location of the installation requirements, and using the built-in mkdocs command:

 version: 2

 build:
   os: ubuntu-24.04
   tools:
     python: "3"

 python:
   install:
     - requirements: requirements.txt

 mkdocs:
   configuration: mkdocs.yml

This will just build a plain MkDocs project, but not a Material for MkDocs project. For this to work, you need to explicitly add the following lines to mkdocs.yml:

theme:
  name: material

This configuration can be found nowhere in the ReadTheDocs documentation (at least I have invested a few minutes searching for it and did not discover it). Instead, it links back to our getting started guide. Thus, if we would link to this guide, we would link to incomplete information, which will lead to questions by users that we then need to answer, as they would get a vanilla MkDocs theme instead.

To be honest, I find this guide to be very confusing and it seems that they just replaced "MkDocs" with "Material for MkDocs" some time ago. Why? I have no idea, because you can actually host any MkDocs project on ReadTheDocs. IMHO, this guide is currently not very well written, but this is just my personal opinion.

We're currently not considering adding this guide for those reasons.

[tleonhardt]

@squidfunk The example code you pasted above from the RTD documentation is what needs to appear in the .readthedocs.yaml file, not in the mkdocs.yml file. I agree that the guide is somewhat confusing and incomplete, but I do not think it is flat out wrong as you were suggesting.

The only advice RTD provides as far as MkDocs Material goes is to provide a link to your Getting Started Guide. The only advice they give regarding what needs to be in the mkdocs.yml file is they show you how to set the site_url.

The guide appears to be written exclusively from the perspective of changes that should be made to adapt an existing working MkDocs Material project to publish it on ReadTheDocs and assumes the knowledge for how to reach a proper configuration for MkDocs Material will be gleaned elsewhere.

P.S. Thanks for creating such an awesome tool for building beautiful documentation!

[niclasheinz]

I have also done some research.

I found this demo repository from RTD, which shows better how exactly the configuration for RTD should look like.

Yes RTD redirects the user directly to our ‘Getting Started’ page, but only to get the basic configuration directly from our manual.

In my opinion, it describes how mkdocs-material documentation can be hosted on RTD.

[squidfunk]

So, first of all, please understand that we cannot link/add/maintan everything in our documentation. We try to provide links to helpful articles, but we must draw the line somewhere. For instance, mkdocs.org already links to this guide. I do not understand why ReadTheDocs specifically talks about Material for MkDocs when the guide is generic.

Regardless, since this is not a guide that is specifically tailored to Material for MkDocs, and has some problems as I mentioned above, we're currently not considering adding it. Even if it would contain a self-contained example, as long as it is general to MkDocs, it should go into the MkDocs documentation.

The section of this documentation should contain fully self contained guides that explain how to deploy a Material for MkDocs site. Thus, I've taken the time and checked the guides that we link under that section again, and decided to do a little quality fresh out. Here are the changes I made + explanations:

1. Removed Codeberg guide – This is a general guide to deploy MkDocs on CodeBerg. CodeBerg is rather niche compared to GitHub, GitLab and Netlify, and the guide has quite a few grammatical and syntactical errors. Until this article is updated and corrected, we remove it, as we don't feel comfortable endorsing it under our brand.
2. Removed Azure guide – This is also a general guide that assumes a lot of prior knowledge, and rather seems like a "memo" on what's important when deploying to Azure. While it definitely has value, it could be more self-contained to guide the user. There are quiet a few discussions on Azure, so maybe somebody can take the time and write up a more comprehensive guide.
3. Fixed some links – Some pages have moved, so I fixed the links.

The Fly.io guide could be improved, but at least is does not require too much prior knowledge and is step-by-step, so we can keep it. I've made the changes in aa101f7. Once the guides are improved, we can add them back ☺️

I'm aware that this might be an unpopular decision, but in the end, we must be careful what we endorse through the name "Material for MkDocs". I hope my reasoning makes sense, and I kindly ask you to accept this decision.

[tleonhardt]

Thanks for the time you put into this and the clear explanation of your philosophy. Your decision makes sense and is fully accepted on my end.

[ericholscher]

Thanks for the comments here. We'd love to work on getting our guide highlighted in the docs.

I do not understand why ReadTheDocs specifically talks about Material for MkDocs when the guide is generic.

A lot of the information on our guide is specific to the Material theme. In particular all of the integration docs that we have is only applicable to the Material theme (eg. https://docs.readthedocs.io/en/stable/intro/mkdocs.html#configure-read-the-docs-search).

Even if it would contain a self-contained example, as long as it is general to MkDocs, it should go into the MkDocs documentation.

It sounds like if we worked to build out a generic MkDocs guide, and then had a page on Integration with Material for MkDocs, then you'd be happy to link to that from your site? If so, I can start working on that, and ensure that we have the information split out in a way that makes sense.

Also, just a heads up:

• This guide is currently 404'ing: https://deborahwrites.com/guides/deploy-mkdocs-material-cloudflare/ -- looks like this is the right link: https://deborahwrites.com/guides/deploy-host-mkdocs/deploy-mkdocs-material-cloudflare/ (Fixed in Fix CF publishing link #7835)
• This guide seems to be a generic Mkdocs guide, and not specific to Material: https://documentation.breadnet.co.uk/cloud/fly/mkdocs-on-fly/ -- I think this is similar to what we can put together on our side, if that works well?

[ericholscher]

I've put together readthedocs/readthedocs.org#11871 which clarifies the guide is about Mkdocs in terms of what we support, but that we generally recommend the Material for MkDocs theme, and we have specific integration information for it. We've spent a decent amount of time working to make sure our features have a nice UX with the theme, so we'd love to find a way to get the docs linked here, and happy to do additional work as suggested.

[squidfunk]

I've outlined my concerns in this comment. Specifically, there's no mention of the required configuration in mkdocs.yml to ensure users actually get Material for MkDocs instead of plain MkDocs. In my opinion, the documentation should also include the pip install mkdocs-material command for clarity.

I might be overly pedantic here, but one thing I've learned about maintaining user-friendly documentation, which I follow as a principle when writing documentation is: avoid making too many assumptions about what users already know. For instance, in our documentation, when we talk about third-party plugins we support, we always include the installation instruction and minimal configuration to get up and running (example). This is our requirement for linking.

If you'd consider revising the guide, we can happily add a link to our publishing guide to give ReadTheDocs more exposure. I hope my reasoning makes sense and is understandable from a maintainer's perspective.