Skip to content

fix(docs): fix theme flicker on docs#9427

Merged
jdx merged 3 commits intojdx:mainfrom
vhespanha:main
Apr 27, 2026
Merged

fix(docs): fix theme flicker on docs#9427
jdx merged 3 commits intojdx:mainfrom
vhespanha:main

Conversation

@vhespanha
Copy link
Copy Markdown
Contributor

Inject data-cfasync="false" attribute into the injected anti-flickering script provided by VitePress, thus avoiding it getting deferred by Cloudflare's Rocket Loader.

this HTML injection method is provided by VitePress itself, but I still think it's a little hacky because we depend on an HTML tag that might change. Because of this, I'll be opening a PR on VitePress itself to add native functionality to add arbitrary attribute to their injected script.

fixes discussion #9393

inject `data-cfasync="false"` attribute into the injected
anti-flickering script provided by VitePress, thus avoiding it getting
deferred by Cloudflare's Rocket Loader.
@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps Bot commented Apr 27, 2026

Greptile Summary

This PR adds a transformHtml VitePress build hook that injects data-cfasync="false" onto the <script id="check-dark-mode"> tag, preventing Cloudflare Rocket Loader from deferring it and causing a theme-flicker on page load. The change is minimal and targeted, affecting only the docs build output.

Confidence Score: 5/5

Safe to merge — the change is a targeted build-time HTML transformation with no runtime risk.

The only known concern (silent no-op if VitePress changes the script tag) has already been raised in a previous review thread. No new P0 or P1 issues were identified.

No files require special attention.

Important Files Changed

Filename Overview
docs/.vitepress/config.ts Adds a transformHtml hook that regex-replaces the VitePress dark-mode script tag to inject data-cfasync="false", preventing Cloudflare Rocket Loader deferral.

Sequence Diagram

sequenceDiagram
    participant VP as VitePress Build
    participant TH as transformHtml Hook
    participant CF as Cloudflare Rocket Loader
    participant Browser

    VP->>TH: HTML output per page
    TH->>TH: inject data-cfasync=false onto dark-mode script tag
    TH-->>VP: patched HTML
    VP->>CF: deploy patched HTML
    CF->>Browser: serve page, skip deferral of flagged script
    Browser->>Browser: dark-mode script runs synchronously, no flicker
Loading

Reviews (3): Last reviewed commit: "Merge branch 'main' into main" | Re-trigger Greptile

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a transformHtml hook in the VitePress configuration to add the data-cfasync="false" attribute to the dark mode script, ensuring it executes correctly without interference from Cloudflare. The reviewer suggested removing the unnecessary async keyword and using a regular expression for the replacement to improve robustness.

Comment thread docs/.vitepress/config.ts Outdated
Comment thread docs/.vitepress/config.ts Outdated
@vhespanha
Copy link
Copy Markdown
Contributor Author

Also worth noting that I wasn't able to test that this actually fixes the issue, since the Rocket Loader thing happens only on prod and it's configured on the Cloudflare dashboard, so I can't easily reproduce the environment by myself (I think).

vhespanha and others added 2 commits April 27, 2026 12:07
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
@jdx jdx merged commit 737a0a2 into jdx:main Apr 27, 2026
35 checks passed
mise-en-dev added a commit that referenced this pull request Apr 28, 2026
### 🚀 Features

- **(task)** add --name-only flag to mise tasks ls by @jdx in
[#9435](#9435)

### 🐛 Bug Fixes

- **(Dockerfile)** install copr-cli via dnf for better dependency
management by @bestagi in [#9421](#9421)
- **(aqua)** drop empty-releases fallback to tags by @jdx in
[#9443](#9443)
- **(docs)** fix theme flicker on docs by @vhespanha in
[#9427](#9427)
- **(lockfile)** update global lockfile on upgrade by @jdx in
[#9442](#9442)
- **(ls-remote)** omit rolling/prerelease from JSON when false by @jdx
in [#9439](#9439)
- **(task)** support usage refs in dependency template tags by @jdx in
[#9424](#9424)
- **(task)** populate usage.cmd for subcommand-only tasks; share
make_usage_ctx by @jdx in [#9431](#9431)
- **(task)** resolve sandbox allow_read/allow_write against task dir by
@jdx in [#9428](#9428)

### 📚 Documentation

- **(site)** add self-hosted page tracker via Cloudflare Worker, drop
GoatCounter by @jdx in [#9430](#9430)

### New Contributors

- @vhespanha made their first contribution in
[#9427](#9427)

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants