Add CF custom error pages by davidfischer · Pull Request #766 · readthedocs/ext-theme

davidfischer · 2026-07-08T22:03:53Z

Excluded these from pre-commit as they intentionally have inline styles
Punted for now on adapting a subset of our styles for inlining
Partially resolves Errors: use application errors from CF and ALBs #469 (the CF part but not the ALB part)

- Excluded these from pre-commit as they intentionally have inline styles - Punted for now on adapting a subset of our styles for inlining

agjohnson · 2026-07-14T00:19:07Z

Punted for now on adapting a subset of our styles for inlining

Do we need to use a subset? We hit this pretty quickly the last time we tried this but maybe the limit was lower.

When you provide a URL for a custom error asset, Cloudflare fetches the page and inlines all referenced resources into the HTML. Images and other binary resources (including those referenced from CSS via url(...)) are inlined as base64-encoded data URLs. CSS and JavaScript files are inlined as plain text inside <style> and <script> tags. The processed page must not exceed approximately 1.5 MB.

I'm guessing what is/was happening is that our CSS is only 800kB on disk but then that tries to also inline the fonts/etc, exceeding 1.5MB.

These error messages should match our existing look and feel, especially on customer documentation projects. They're pretty one-off feeling right now. It's better than Cloudflare branding these error pages at least though.

There are some modifications that would make this fit better temporarily, but I also won't want to get too far away from finishing this work either way. We'll want to follow up with pages that use our existing styles and structure so these don't feel so out of place.

agjohnson

Assuming reusing our styles is a harder task, this looks okay temporarily. I commented on the first file, but most of that applies to all the files. A second pass at these can explore trimming our existing CSS down and perhaps consider a dark theme, though I wouldn't support that unless we decide to support our dark theme without user authentication.

agjohnson · 2026-07-13T22:31:15Z

+      --text-color: #18181b;
+      --box-bg: #ffffff;
+      --border-color: #e4e4e7;
+      --accent-color: #dc2626; /* Red for blocking */


We should match the already used site colors here, especially for the accents though.

agjohnson · 2026-07-13T22:34:04Z

We already have the template path readthedocsext/theme/errors/, let's use errors in the path instead of error-pages to reduce confusion between the two.

agjohnson · 2026-07-14T00:20:16Z

+    /* Automatic Dark Mode Support */
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg-color: #09090b;
+        --text-color: #f4f4f5;
+        --box-bg: #18181b;
+        --border-color: #27272a;
+        --accent-color: #ef4444;
+        --light-svg-display: none;
+        --dark-svg-display: block;
+      }
+    }


We don't support dark themes on the current error pages and this is probably most of what feels so out of place currently. I might say drop dark mode from this pass.

agjohnson · 2026-07-14T00:22:12Z

+    svg.dark {
+      display: var(--dark-svg-display);
+    }


No need for multiple SVGs, we can use CSS to invert:

Suggested change

svg.dark {

display: var(--dark-svg-display);

}

svg.dark {

filter: invert(100) brightness(110);

}

That assumes the dark color text SVG for use on white background, inverted to be (brighter) white.

agjohnson · 2026-07-14T00:24:59Z

+      <svg class="dark"
+           version="1.1"
+           id="svg"
+           xmlns="http://www.w3.org/2000/svg"
+           xmlns:xlink="http://www.w3.org/1999/xlink"
+           x="0px"
+           y="0px"
+           viewBox="694 197 2000 400">


I don't think we need to hardcode this. If you reference the hosted SVG, Cloudflare will inline it for us. Then we don't need to keep multiple hardcoded copies around.

https://app-assets.readthedocs.org/readthedocsext/theme/images/logo-wordmark-dark.svg

There's a lot of advantages to having the page served by others (Cloudflare) being a single self-contained page. We can rely on Cloudflare to handle serving other content correctly, but it'd be a lot simpler and a lot harder to get wrong if the error page was entirely self-contained.

It would still be self-contained, Cloudflare automatically does all of the inlining instead of referencing a URL¹:

When you provide a URL for a custom error asset, Cloudflare fetches the page and inlines all referenced resources into the HTML. Images and other binary resources (including those referenced from CSS via url(...)) are inlined as base64-encoded data URLs.

Footnotes

https://developers.cloudflare.com/rules/custom-errors/#custom-error-assets ↩

No I get that. I just think there are additional advantages to having it actually be self-contained by design rather than relying on Cloudflare to magically make it self-contained.

Yeah I get that it's more explicit, but if we aren't hitting any issues with Cloudflare inlining of these files then it seems fine to lean on Cloudflare and keep our maintenance simple. The long term goal would be to feed Cloudflare these pages through our templates, so would end up relying directly on static file collection.

…anaged_challenge.html Co-authored-by: Anthony <aj@ohess.org>

davidfischer · 2026-07-15T23:28:23Z

Do we need to use a subset? We hit this pretty quickly the last time we tried this but maybe the limit was lower.

We don't strictly need to but there's a lot of nice aspects of having the entire error page being self-contained. We can rely on Cloudflare to "just handle it" but it'd be a lot harder to get wrong and a lot more portable if we had self-contained error pages.

I can attempt to match the styles/colors a little closer and possibly inline a small subset, but unless you are dead-set on it, I'd advise against using our full styles. If we do go that route, I'd probably just make this a template that uses other styles rather than a static file collected with collectstatic.

agjohnson · 2026-07-18T02:07:35Z

Well, I'd say just the changes above are enough for a first pass -- skipping dark mode and using colors from our styles.

Long term, these error pages should definitely match our dashboard errors but for a first pass the basic style is okay. They just should stick to a look and feel that isn't too far removed from our current, it's a bit confusing when we give varying UX/styles.

When we polish these up to match our current styles, I wouldn't use the full stylesheet here due to the size but I would use just the rules we need to make it look like the other error pages.

And yeah, the idea was to make this a template long term too. But similarly, we can keep this simple by just leaving them as static files to start. Eventually we'd author them alongside all of our other error templates and feed them to Cloudflare through our existing ErrorView. In this world, our templates handle the static files so we wouldn't have hardcoded inlines for images/etc.

- Remove dark mode - Add colors from dashboard stylesheets - Add border-bottom to H1

davidfischer · 2026-07-22T16:53:43Z

Ok, I updated the styles on these pages to match the dashboard styles. They're still static, self-contained HTML rather than templates, but this should give us a first pass.

Add CF custom error pages

2635b6f

- Excluded these from pre-commit as they intentionally have inline styles - Punted for now on adapting a subset of our styles for inlining

davidfischer requested a review from a team as a code owner July 8, 2026 22:03

davidfischer requested a review from agjohnson July 8, 2026 22:03

Error pages have intentionally inlined styles

b541a30

agjohnson reviewed Jul 14, 2026

View reviewed changes

Update readthedocsext/theme/static/readthedocsext/theme/error-pages/m…

d20717e

…anaged_challenge.html Co-authored-by: Anthony <aj@ohess.org>

Adapted challenge pages to our styles

b87f380

- Remove dark mode - Add colors from dashboard stylesheets - Add border-bottom to H1

Uh oh!

Conversation

davidfischer commented Jul 8, 2026

Uh oh!

agjohnson commented Jul 14, 2026

Uh oh!

agjohnson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

davidfischer commented Jul 15, 2026

Uh oh!

agjohnson commented Jul 18, 2026

Uh oh!

davidfischer commented Jul 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants