Readthedocs.org: MkDocs builds: allow to use MkDocs own themes

[kirill-korniakov]

Is it possible to use native MkDocs themes in the RTD builds? If not, it would be a valuable addition.

Here is what I'm trying to achieve. I'm trying to setup RTD build for a GitHub project that uses mkdocs: https://readthedocs.org/projects/devtools-course-practice-mkdocs/. This is just an experiment, but it seems that the current level of mkdocs support by RTD is very limited (making it almost useless):

1. The RTD theme is broken (#974, https://github.com/tomchristie/mkdocs/issues/127), so the pages are not displayed correctly. I'm talking about lists first of all.
2. And we can't replace RTD theme with default MkDocs theme. At least I don't know how to override the RTD theme in MkDocs builds. Is it supported and documented? I tried to use theme: mkdocs in my mkdocs.yml, but it doesn't work.

So, it seems that MkDocs support is very experimental today, and RTD is still primarily targeted for Sphinx projects. But what are the plans in this direction? Are you going to support native mkdocs themes?

[dnrce]

At present the theme is hard-coded: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/backends/mkdocs.py#L147

[Toilal]

:+1:

[ericholscher]

The main reason is because the default mkdocs themes don't have blocks defined, which means we can't override any of the templates. This makes it hard for us to inject some of the page-level context that lets us provide RTD features on top. It's something that we need to get into upstream mkdocs before we can really support it on RTD.

[cjerdonek]

In the meantime, I think it would be good to add to the FAQ that custom themes aren't currently supported when using mkdocs (e.g. after this question). It might also be good to add a note here: https://docs.readthedocs.org/en/latest/theme.html . The current note at the top is a bit vague about what it's referring to.

It wasn't clear to me that custom themes weren't supported until I found this issue.

[QCaudron]

Agreed with @cjerdonek : I was surprised when my locally-built mkdocs website used the theme I wanted, and that the version on RTD didn't reflect this. Not a _major_ issue, but would be fantastic if they could be implemented, or that a note be made somewhere. Thanks !

[nicholas-leonard]

Same issue for me. Still not documented.

[d0ugal]

Adding a note here probably makes most sense: https://github.com/rtfd/readthedocs.org/blob/master/docs/getting_started.rst

AFAICT, this is the only part of the docs that covers MkDocs.

[roll]

:+1:

[d0ugal]

The main reason is because the default mkdocs themes don't have blocks defined, which means we can't override any of the templates. This makes it hard for us to inject some of the page-level context that lets us provide RTD features on top. It's something that we need to get into upstream mkdocs before we can really support it on RTD.

@ericholscher What blocks are needed? It would be good if we could define this somewhere, somehow. I'd be then happy to make sure MkDocs conforms to this.

[d0ugal]

From what I can tell, the only blocks required are for search integration and the the version switcher thing.

[marcelstoer]

Definitely would love to see some progress here. I guess things become even more complicated once the MkDocs themes are only available as part of http://mkdocs.github.io/mkdocs-bootswatch/ anymore.

[d0ugal]

Not really, that won't complicate anything I don't think.

[marcelstoer]

that won't complicate anything I don't think

Don't want to take this issue OT but wouldn't RTD have to make mkdocs-bootswatch available on their infrastructure _in addition_ to MkDocs?

[d0ugal]

Users can specify any arbitrary Python packages they want with RTD. If this only allowed MkDocs supported themes it wouldn't be worth the effort :)

[tatablack]

Apologies, but I am a bit unclear as to the status of this issue. Is there still work required on MkDocs's side (to define the aforementioned blocks), or we "just" need to make RTD's MkDocs builder check the theme specified in mkdocs.yml and use it if it's there?

[d0ugal]

@tatablack I believe the work is just needed on the RTD side. It is true that MkDocs could possibly not integrate well if they don't match up with RTD's expectations (but I think this is also true with custom Sphinx themes).

need to make RTD's MkDocs builder check the theme specified in mkdocs.yml and use it if it's there?

It's actually simpler than that. At the moment RTD overwrites whatever theme users specify, to enable other themes RTD just needs to stop overwriting this setting.

[tatablack]

Thanks, @d0ugal. I just opened a PR (with an admittedly simplistic solution), let's see how it goes.

[agjohnson]

What's the status of RTD being able to support custom themes? Would the RTD features, such as the doc flyout be implemented on custom themes?

As it stands, we're opposed to allowing custom themes on mkdocs projects on RTD. The user experience is degraded without the RTD additions to documentation, and to allow custom themes would only further dilute our efforts to a cohesive user experience.

I agree custom themes on Sphinx leads to the same effect, a degraded user experience. I'd much rather a common interface to documentation across projects. At least with Sphinx we have the ability to control parts of the templating process to allow for injection across all themes.

[tatablack]

@agjohnson, I agree with the label you put on PR #2188 (Needed: design decision), so I'd like to argue in favour of custom themes.

1. As long as the (potential) loss of certain features is well documented, it should be up to the documentation authors to make an informed decision, evaluating the benefits of a custom theme for their audience and comparing them with the downsides of not providing certain RTD features that their readers might be familiar with from other RTD documentation sets.
2. If it is possible/easier to choose a custom theme, some of them _might_ become more popular, and this _might_ lead to improvements in the themes themselves, either by the original authors or by whoever in the community is using them. I do realise this is hypothetical, but surely if I cannot use a theme I won't feel compelled to improve it.
3. Sphinx vs. MkDocs. What I understand from this thread is that the level of integration between RTD and MkDocs is not the same as with Sphinx (being able to "control parts of the templating process", as you mentioned). However (and this might be off-topic for this thread, feel free to shut me up if that's the case) I wasn't able to find exactly which hooks are missing. @d0ugal: are you aware of what improvements could be made on MkDocs side, and if yes, are they at all possible?

[roll]

A little bit strange issue - it's about 2 years but I suppose there is no real understanding what are requirements to be a RTD theme. What should be in MkDocs theme to make it equal to custom Sphinx theme?

If you will decide to shutdown custom themes at all - OK. But while it's allowed it looks like there is no reason to limit MarkDown writers this way in comparison of Sphinx writers.

[chimeno]

¿Whats the status of this issue?
I mean, its a won't fix or we can make something to make mkdocs themes compatible with RTD?

[ericholscher]

As I mentioned in #2188 -- we've decided not to support this, for the reasons listed there.