Deprecate mdn-sphinx-theme



2 years ago
a year ago


(Reporter: jwhitlock, Assigned: jwhitlock)




(Whiteboard: [specification][type:change])



2 years ago
What feature should be changed? Please provide the URL of the feature if possible.
The mdn-sphinx-theme is a skin that makes the Kuma documentation look like the MDN documentation:

We should switch to a active, community-supported theme and abandon the mdn-sphinx-theme.

What problems would this solve?
The mdn-sphinx-theme is often out-of-date with MDN. It has not been updated in 8 months. It is non-trivial to update it [1], and "theme paths" pollute the Kuma base templates, to exclude things like Google Analytics and helpfulness surveys.

Our theme lacks common features of other Sphinx themes, such as documentation search and permanent links to in-page sections (often exposed by a "¶" that appears on hover).  This makes the Kuma documentation less useful than other project's documentation, like Bedrock [2].  We would add these and other features easily by switching to an active, community-supported theme.

Four years ago, one of the design goals of MDN was to collect all the Mozilla documentation into one documentation hub or network (see bug 877197).  The mdn-sphinx-theme was an experiment into what this might look like (bug 877197). However, MDN's documentation style isn't a perfect match for these project's needs (bug 920314). 

In those four years, it is becoming clearer that:
* MDN is best for open web documentation where a community contributes small changes and translations
* Sphinx is a great solution for product documentation maintained by the product team
* ReadTheDocs is the de facto hub for open source project documentation, and should be supported in that role [3].

There may be a place for a Mozilla-default Sphinx theme, but MDN shouldn't be the template.

The current mdn-sphinx-theme loads assets from the MDN CDN, and relies on old versions of assets being kept around indefinitely.  This may change as we move to AWS and serving only the latest version of assets, relying on the external CDN provider to cache assets for a limited amount of time (1-12 months).  The theme would need to be updated to include the assets in the package, which will require some development effort, and would make a bulky, non-optimized theme.


Who would use this?
Kuma would stop using mdn-sphinx-theme.

There are a handful of other projects that continue to use the theme [4], but most appear to not have been updated in a few years, and continue to use old releases.  If these projects are still maintained, they can switch to a community-supported Sphinx theme.


What would users see?
Kuma documentation users would see docs that look more like other open-source documentation, and have all the features like search and permalink that they expect.

What would users do? What would happen as a result?
Users would continue using docs.

Kuma would drop Sphinx-generation code paths in the code and templates, making our base templates easier to understand and upgrade.

Project owners wouldn't waste time considering mdn-sphinx-theme

Is there anything else we should know?
Documentation is hard. People don't read. If your project documentation doesn't make a lot of sense, then you need to work on your developer interfaces.
Keywords: in-triage

Comment 1

a year ago
As predicted, the move to AWS (bug 1110799) has broken the theme. We're moving to the Alabaster theme: mozilla/kuma#4457 .


a year ago
Assignee: nobody → jwhitlock
Priority: -- → P1

Comment 3

a year ago
Added a deprecation warning to
Last Resolved: a year ago
Resolution: --- → FIXED

Comment 4

a year ago
Commits pushed to master at
bug 1361729: Remove mdn-sphinx-template support

* Remove "is_sphinx" tests from base template
* Remove sphinx.css generation
* Remove URLAbsolutionFilter from content filters
* Remove ./ generate_sphinx_template
Merge pull request #4487 from jwhitlock/remove-sphinx-template-1361729

bug 1361729: Remove mdn-sphinx-template support
You need to log in before you can comment on or make changes to this bug.