# Why does local django docs have a different styling/theme than the official one? **URL:** \ **Category:** Website\ **Created:** [July 7, 2024, 2:31pm UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761 "2024-07-07T14:31:22Z")\ **Posts on this page:** 13\ **Page:** 1
**Author:** ![RosanaRufer](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/rosanarufer/32/22103_2.png) [@RosanaRufer](https://forum.djangoproject.com/u/RosanaRufer)\ **Post date:** [July 7, 2024, 2:31pm UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/1 "2024-07-07T14:31:22Z")
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](https://django.readthedocs.io/en/stable/)) 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](https://github.com/django/django/tree/main/docs) or else, try and make the local theme the same as the official one. Thanks ---
**Author:** ![bmispelon](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/bmispelon/32/38_2.png) [@bmispelon](https://forum.djangoproject.com/u/bmispelon)\ **Post date:** [July 11, 2024, 10:59am UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/2 "2024-07-11T10:59:42Z")
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 ✨ ---
**Author:** ![medmunds](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/medmunds/32/22140_2.png) [@medmunds](https://forum.djangoproject.com/u/medmunds)\ **Post date:** [May 29, 2026, 7:48pm UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/3 "2026-05-29T19:48:10Z")
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? 😁) 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](https://us1.discourse-cdn.com/flex026/uploads/djangoproject/original/3X/0/b/0b441d003add0b3f2b78433a9e0cd9482571a532.png) 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](https://us1.discourse-cdn.com/flex026/uploads/djangoproject/original/3X/a/7/a79bb4a282ba83b402a10dc6f54cc2b299d543a3.png) 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](http://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.] ---
**Author:** ![medmunds](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/medmunds/32/22140_2.png) [@medmunds](https://forum.djangoproject.com/u/medmunds)\ **Post date:** [June 2, 2026, 10:10pm UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/4 "2026-06-02T22:10:14Z")
I opened ticket [#37138 (Outdated docs CSS in local and preview builds) – Django](https://code.djangoproject.com/ticket/37138) to have the styles in Django Sphinx builds match the ones on [docs.djangoproject.com](http://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](https://github.com/django/djangoproject.com/tree/main/djangoproject/scss) 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](https://github.com/django/djangoproject.com/blob/main/djangoproject/scss/_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.) ---
**Author:** ![smallsaucepan](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/smallsaucepan/32/31265_2.png) [@smallsaucepan](https://forum.djangoproject.com/u/smallsaucepan)\ **Post date:** [June 3, 2026, 2:40am UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/5 "2026-06-03T02:40:46Z")
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?](https://forum.djangoproject.com/t/where-should-shared-css-js-assets-for-code-djangoproject-com-live/45201) @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](https://www.djangoproject.com/contact/foundation/) ---
**Author:** ![medmunds](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/medmunds/32/22140_2.png) [@medmunds](https://forum.djangoproject.com/u/medmunds)\ **Post date:** [June 4, 2026, 2:31am UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/6 "2026-06-04T02:31:28Z")
I’ve opened draft PR [Fixed #37138 -- Borrowed djangoproject.com theme for docs builds. by medmunds · Pull Request #21416 · django/django · GitHub](https://github.com/django/django/pull/21416). 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](https://django--21416.org.readthedocs.build/en/21416/) 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. ---
**Author:** ![medmunds](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/medmunds/32/22140_2.png) [@medmunds](https://forum.djangoproject.com/u/medmunds)\ **Post date:** [June 9, 2026, 12:03am UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/7 "2026-06-09T00:03:18Z")
I’ve completed the missing parts of the [PR to update Django’s docs theme](https://github.com/django/django/pull/21416) 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). ---
**Author:** ![nessita](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/nessita/32/12194_2.png) [@nessita](https://forum.djangoproject.com/u/nessita)\ **Post date:** [July 2, 2026, 8:14pm UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/8 "2026-07-02T20:14:11Z")
Following up here as Mike asked in [the PR](https://github.com/django/django/pull/21416#issuecomment-4753346289), now that the 6.1beta is out. We (Fellows) have two concerns about ingesting the [djangoproject.com](http://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](http://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](https://github.com/django/django/pull/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. ---
**Author:** ![medmunds](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/medmunds/32/22140_2.png) [@medmunds](https://forum.djangoproject.com/u/medmunds)\ **Post date:** [July 2, 2026, 10:12pm UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/9 "2026-07-02T22:12:01Z")
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](http://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… > [@nessita](#): > > **3. A different direction (my strong preference).** I’d rather drop our bespoke local theme entirely and adopt the Read the Docs theme […] (or another well known and well maintained theme) […] 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](https://pradyunsg.me/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.) > [@nessita](#): > > **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. 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.) > [@nessita](#): > > **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. 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](https://github.com/django/djangoproject.com/blob/main/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. ---
**Author:** ![nessita](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/nessita/32/12194_2.png) [@nessita](https://forum.djangoproject.com/u/nessita)\ **Post date:** [July 3, 2026, 9:18pm UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/10 "2026-07-03T21:18:29Z")
> [@medmunds](#): > > The [Furo](https://pradyunsg.me/furo/) theme seems quite popular and well maintained. Great, I wanted to use this theme too but figured the RTD theme was more established, but your advice here has weight +1. > [@medmunds](#): > > If the DSF doesn’t have the rights to relicense and permit redistribution of the style source, that should really get corrected. Good point and before doing anything in this front, I will discuss with the Board. Thank you! ---
**Author:** ![nessita](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/nessita/32/12194_2.png) [@nessita](https://forum.djangoproject.com/u/nessita)\ **Post date:** [July 6, 2026, 2:03am UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/11 "2026-07-06T02:03:24Z")
There is some exploratory work for the theme reset in [Fixed #37138 – Replaced the custom docs HTML theme with Furo.](https://github.com/nessita/django/pull/53): - 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 ---
**Author:** ![medmunds](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/medmunds/32/22140_2.png) [@medmunds](https://forum.djangoproject.com/u/medmunds)\ **Post date:** [July 6, 2026, 4:14pm UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/12 "2026-07-06T16:14:42Z")
Heh, looks like we had the same weekend project. In addition to Furo, I tried building with [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html). (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: - [Furo RTD preview](https://django--21585.org.readthedocs.build/en/21585/) build and related [PR 21585](https://github.com/django/django/pull/21585) - [Pydata RTD preview](https://django--21586.org.readthedocs.build/en/21586/index.html) build and related [PR 21586](https://github.com/django/django/pull/21586) 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](https://code.djangoproject.com/ticket/35874#comment:7). ---
**Author:** ![nessita](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/nessita/32/12194_2.png) [@nessita](https://forum.djangoproject.com/u/nessita)\ **Post date:** [July 6, 2026, 9:09pm UTC](https://forum.djangoproject.com/t/why-does-local-django-docs-have-a-different-styling-theme-than-the-official-one/32761/13 "2026-07-06T21:09:04Z")
> [@medmunds](#): > > Neither theme is perfect, but both are quite good and improvements over what we have now: > > - [Furo RTD preview](https://django--21585.org.readthedocs.build/en/21585/) build and related [PR 21585](https://github.com/django/django/pull/21585) > - [Pydata RTD preview](https://django--21586.org.readthedocs.build/en/21586/index.html) build and related [PR 21586](https://github.com/django/django/pull/21586) 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.