From def173cb85ca30e6bd74ea30747d1c8171a79075 Mon Sep 17 00:00:00 2001 From: Adam Zapletal Date: Fri, 19 Dec 2025 09:11:48 -0600 Subject: Use CSS instead of JavaScript for floating warning Some of the functionality of the floating warning on unsupported and in-development documentation versions was implemented using JavaScript. This is longer necessary if we use the following approach with modern CSS: Attach the warning element the top of the page with `position: sticky`. This almost solves the problem, but we still have to scroll past header elements when an internal page link is clicked. This is achieved with a combination of the `:has` pseudo-class and the `scroll-margin-top` property. We apply `scroll-margin-top` to elements that can be scrolled to by their `id` attribute. This is done with responsive breakpoints to get appropriate spacing when the floating warning has one, two, or three lines of text. Thanks to `:has`, this only happens when a warning element is on the page. The modern CSS features used are widely-supported: - https://caniuse.com/css-has - https://caniuse.com/css-sticky - https://caniuse.com/mdn-css_properties_scroll-margin-top Other than making the primary CSS changes and removing the related JavaScript, this patch does the following: - Simplify the CSS so that the class on all floating warning elements implements the common rules and the CSS for the IDs on the elements implements the colors - Add a `z-index` to warning elements so that they always display in front of the header element - Move the floating warning element to the top of the page in the HTML - Remove the `body_extra` block that was only being used by the floating warning element - Add a new `before_header` block for the floating warning element Thank you to Baptiste Mispelon and Thibaud Colas for helping me arrive at this solution. --- docs/templates/docs/doc.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/templates/docs/doc.html b/docs/templates/docs/doc.html index 512d6cfb..8bce6c2f 100644 --- a/docs/templates/docs/doc.html +++ b/docs/templates/docs/doc.html @@ -34,7 +34,7 @@ title="{% trans "Django documentation" %}"> {% endblock link_rel_tags %} -{% block body_extra %} +{% block before_header %} {% if release.is_dev %} {% if "internals" not in docurl %}{# The dev version is canonical for internals/. #}
@@ -50,7 +50,7 @@ {% trans "This document is for an insecure version of Django that is no longer supported. Please upgrade to a newer release!" %}
{% endif %} -{% endblock body_extra %} +{% endblock before_header %} {% block content %}
-- cgit v1.3