Why does local django docs have a different styling/theme than the official one?

Django Internals Website
1

When running django documentation to preview my changes locally, I spent a fair amount of time thinking something was missing because it looks [like this], but then I asked (Django documentation — Django 5.0.6 documentation) other contributors and they said this is the usual local theme.
I was wondering why this is the case as it added a bit of confusion and it’s usually better to be able to preview things as they’ll finally be rendered in production.

Hoping I can add an explanation about this in the “documentation contribution” guidelines or in the README.md or else, try and make the local theme the same as the official one.

Thanks

1 Like
Django Fellow Report - Natalia - 2026
Increasing size of HTML text in django docs default theme
2

Hi,

That’s a great question, and I agree that this mismatch is confusing.

I’m not sure I have the whole answer to your question (and there might be multiple “why”-s here), but I think I can shed some light on some aspects at least.

The yellow/green style (which you get when building the docs locally, or - as you pointed out - on ReadTheDocs) is Django’s old official theme. This is how the website used to look like, until it was overhauled about 10 years ago with a new design, which we still have today.

I was on the team that led the implementation of that “new” design, and I have a vague memory that the topic of the local docs theme was mentioned, but that it was decided that the “old” theme would stay.
My recollection is that it had something to do with licensing. I might be wrong here, but the old theme has the same license as Django (being included in the repository alongside the code), whereas the new theme does not have a public license (the DSF owns the rights I think).

Because this has to do with licensing, it might be tricky to change things, but maybe the color palette could be changed at least? Surely that falls within the license requirements (he says, being completely ignorant of licensing laws).

In any case, if you do end up making a pull request to the README, please feel free to tag me if you have questions or want a review (I have the same username on github or in the Django #contributor-discussion channel).

Thanks again for raising this up :sparkles:

2 Likes
3

I wanted to raise this again and see if we can find a solution. The CSS mismatch between the production docs site vs. local/preview builds complicates working on the docs. It’s not just color schemes: there are (visual) semantic differences between the two styles. Example below.

If there’s a licensing issue with the DSF owning the docs site styles, I’d think that could be solved somehow. (Do we know anyone at the DSF? :grin:) Maybe we could vendor the DSF’s CSS into Django’s docs with the DSF’s license intact, like we do for other vendored code (such as docs/_theme/djangodocs/static/fontawesome).

Here’s an example: we want to versionchanged:: two things related to the same function. There’s a bug in my reST source—can you spot it from the local docs build? (I didn’t.)

docs-screenshot-local-build
docs-screenshot-local-build1274×198 22.4 KB

The mistake becomes visible on the production site: both of those paragraphs were meant to be inside the versionchanged:: directive, but only one is:

docs-screenshot-live-site
docs-screenshot-live-site1142×290 28.4 KB

I ran into this particular issue in my own recent documentation work. But I’m guessing it’s not the only significant difference between the old and new docs CSS.

[Related aside: The bundled CSS on docs.djangoproject.com is missing a /*! license or copyright comment for DSF’s CSS, making it seem like it’s covered by FontAwesome’s MIT license statement from earlier in the bundle.]

3 Likes
4

I opened ticket #37138 (Outdated docs CSS in local and preview builds) – Django to have the styles in Django Sphinx builds match the ones on docs.djangoproject.com.

Looking into it a bit, I think the issues may be more technical and content than licensing-related:

  • The djangoproject style source is scss, so needs to be compiled to css. We might not want to depend on an scss compiler for Django docs builds. (Or it might be OK? We already have other docs build requirements.)
  • The docs-specific styles are mixed in with other djangoproject.com site styles, and it might be difficult to separate them. (See _style.scss. This includes things we’d want, like shared layout and base styles, plus things we don’t need, like fundraising and hero modules. But maybe that extra CSS is OK for now to get styles matching, and we could work on cleaning it up later?)
  • Fwiw, the djangoproject.com source is under a BSD license, so I think we could certainly vendor parts of it into Django with appropriate license attribution. (There might be some concerns about the trademarked logos that the CSS places in the header, but we could maybe avoid those. Also, IANAL.)
2 Likes
5

Perhaps related, someone is working on dark mode for the issues site, and had questions about where shared resources should live - Where should shared CSS/JS assets for code.djangoproject.com live?

@kehach07 would you mind describing your intended approach? Maybe there is a common repo of foundational styles / css variables we can work towards?

Regarding the legalities, can we just cold call? Django Software Foundation

1 Like
6

I’ve opened draft PR Fixed #37138 -- Borrowed djangoproject.com theme for docs builds. by medmunds · Pull Request #21416 · django/django · GitHub. It mostly works, but needs some cleanup and is missing auxiliary pages like indexes and search results.

You can see the results in the RTD preview build for that PR.

The main difficulty turned out to be adapting (and reducing) the djangoproject.com templates for use directly with Sphinx. There will be a bit of effort to monitor future upstream template changes, but looking at the history very few changes would have affected the parts I copied anyway. (So it might be OK to just ignore upstream template updates until something breaks.)

For updating the CSS and other static assets, I added a docs Makefile recipe that automates fetching them from the djangoproject.com repo. This is run only on demand—not as part of ordinary docs builds—and the results are meant to be committed to the django repo.

Let me know what you think or if you spot any problems.

3 Likes
7

I’ve completed the missing parts of the PR to update Django’s docs theme and believe it’s ready for review. (And I found a few other bugs along the way, reported separately.)

Somewhat related, how would we feel about changing the ReadTheDocs config to use Sphinx’s “dirhtml” builder? That would make the URLs in PR preview builds closer to what you’d find on docs.djangoproject.com (no .html extensions).

1 Like
8

Following up here as Mike asked in the PR, now that the 6.1beta is out.

We (Fellows) have two concerns about ingesting the djangoproject.com CSS into Django, and then I (Natalia) have a proposal to look at the opposite direction.

1. Licensing/provenance. The current website CSS styling was contributed as an in-kind donation, and that donation does not cover/include shipping the CSS inside Django’s source tree/released artifacts. This is the same hesitation @bmispelon raised earlier in the thread, and I don’t think we can wave it away.

2. Maintenance. A copy of the compiled CSS in django/django would drift from its source. Realistically we wouldn’t keep it in sync, and we’d recreate the exact staleness this ticket is about, just against a newer baseline.

3. A different direction (my strong preference). I’d rather drop our bespoke local theme entirely and adopt the Read the Docs theme, instead of ingesting the production CSS. Adopting sphinx-rtd-theme fixes exactly what the ticket is about (the current local theme has usability problems, is missing semantically-important styles, and has no dark mode), with zero licensing risk and zero sync burden, since it’s maintained by its own community.

Worth making explicit why this is safe docs.djangoproject.com doesn't use the Sphinx HTML theme at all. It consumes the JSON builder output and applies the site's own templates and styles, so docs/_theme/djangodocs/ only affects local and RTD preview builds therefore production is unaffected by whatever we pick there. The custom directives emit their HTML from docs/_ext/djangodocs.py regardless of theme, so switching themes doesn't change the content the site ingests.

There’s a second benefit I care about: it removes the confusion. Right now local looks a little somehow like the website but not quite, and that near-match is what trips authors up (IMHO). Adopting something clearly different, and equal to a widely known theme, sets clear expectations: contributors know they’re previewing in a standard Sphinx theme, not a stand-in for docs.djangoproject.com. A maintained theme with clear admonition boxes would also have surfaced the versionchanged issue that Mike raised.

The one genuinely functional piece in our django theme is the ~46-line pure-CSS console-tabs stylesheet, which we can keep as a small supplemental stylesheet on top of the base theme.

@medmunds I really appreciate the work in PR #21416 but I’d love to redirect that toward adopting sphinx-rtd-theme (or another well known and well maintained theme), which gets us the same benefit on a foundation we can actually sustain.

1 Like
9

Thanks for following up @nessita. I think I agree with your preference for adopting a well-maintained Sphinx theme rather than trying to maintain our own.

Incidentally, I just learned that downloadable copies of the docs from docs.djangoproject.com use the (old) theme that’s bundled with Django, so don’t match what you see on the docs site anyway.

Some specific responses, in reverse order…

I agree. And at risk of bikeshedding…

I would caution against sphinx-rtd-theme. (I say this as someone who has long had a todo item to replace it in my own projects.) Its CSS is complicated and fragile (based on the Wyrm and Bourbon sass libraries that haven’t been maintained for over a decade). Perhaps as a result, it has been prone to regressions.

The Furo theme seems quite popular and well maintained. (PyPA has adopted it for many of its tools.) It supports light/dark mode, can be customized with CSS properties, and is MIT licensed. (My only concern is there may be some accessibility issues with its admonition fontsize and contrast, but there are CSS properties to change those if necessary.)

True, but at least it is a newer baseline. And unlike the current theme, it has upstream source that’s actively maintained. With an eye toward accessibility. (And fwiw, my PR did try to automate the syncing process. But I take your point.)

So… this status is not reflected in the djangoproject.com repo, which currently seems to place the source for the styling under the same permissive BSD license as everything else (that isn’t vendored) in the repo. If the DSF doesn’t have the rights to relicense and permit redistribution of the style source, that should really get corrected.

10

Great, I wanted to use this theme too but figured the RTD theme was more established, but your advice here has weight +1.

Good point and before doing anything in this front, I will discuss with the Board. Thank you!

11

There is some exploratory work for the theme reset in Fixed #37138 – Replaced the custom docs HTML theme with Furo.:

  • commit 1 slightly unrelated to be cherry-picked as its own PR,
  • commit 2 the juicy one, uses “string” labels for the console OS tabs,
  • commit 3 optionally uses icons for the OS tabs,
  • commit 4 full cleanup of remainings
12

Heh, looks like we had the same weekend project. In addition to Furo, I tried building with pydata-sphinx-theme. (There were a couple of things about Furo that bothered me after seeing it in action.)

Neither theme is perfect, but both are quite good and improvements over what we have now:

I also updated the console-tabs djangodocs Sphinx extension to improve compatibility with any theme and fix a handful of other problems (first commit in each PR). For the console-tabs labels, I’d suggest dropping the icons and going with plain text—here’s why.

1 Like
13

These two look great! I like boths, though locally I had furo being stubborn in that if I switched to dark mode, clicking on any link would take me to the page with light mode on. So that was annoying.

PyData theme looks very polished, I like the search input in the navbar, and the dark/light switcher is fancy too. I’m fine with either, but I’m now convinced that we should adopt a mature theme like these instead of having our own.

I’ll close my PR in favor of yours, though I would like to see the set of cleanup changes be its own commit to make the review a bit easier. Also merging this would require some pre-requisite changes in the website, as I’m sure you are aware of since you have been investigating that already.