First interactive code example by paoloredis · Pull Request #2897 · redis/docs

paoloredis · 2026-03-17T14:19:19Z

Note

Medium Risk
Adds a large amount of new client-side JS/CSS and templating in baseof.html to support interactive Thebe/Binder execution, which could impact site-wide rendering/performance and introduce subtle UI regressions. CI changes also affect all versioned doc builds by adding a make components step.

Overview
Introduces a new jupyter-example shortcode that renders step-based, toggleable code blocks backed by Thebe/Binder, including per-page Binder ref/kernel configuration derived from example metadata.

Updates the base layout to conditionally load and configure Thebe (lazy-loaded) and adds substantial styling/JS to manage kernel sessions, execution, output placement, and step/full-file toggling behavior.

Migrates the redis-py landing examples to use jupyter-example, tweaks global copy-button injection to skip Thebe blocks, adds CSS for Thebe visibility/highlight behavior, and updates CI to run make components in versioned build jobs.

^{Written by Cursor Bugbot for commit 0bd9a00. This will update automatically on new commits. Configure here.}

github-actions · 2026-03-17T14:19:42Z

DOC-6375

github-actions · 2026-03-17T14:19:54Z

Staging links:
https://redis.io/docs/staging/DOC-6375/develop/clients/redis-py/

jit-ci · 2026-03-17T14:20:48Z

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

^{Security scan by Jit}

layouts/_default/baseof.html

layouts/shortcodes/jupyter-example.html

dwdougherty

I didn't heavily scrutinize the code, but the results look great!

layouts/shortcodes/jupyter-example.html

andy-stark-redis

This is excellent, but if you can fix the issues I mentioned then that would be very helpful :-)

content/develop/clients/redis-py/_index.md

layouts/_default/baseof.html

layouts/shortcodes/jupyter-example.html

mich-elle-luna · 2026-03-17T19:43:32Z

Thank you this is looking great

cursor · 2026-03-18T08:47:44Z

layouts/shortcodes/jupyter-example.html

+  {{ $binderLine := index $binderMatches 0 }}
+  {{ $binder = replaceRE (printf `^%s BINDER_ID ` $commentPrefix) "" $binderLine }}
+  {{/* Store binder ref in page scratch for use in baseof.html */}}
+  {{ .Page.Scratch.Set "binderRef" $binder }}


Scratch vs Store inconsistency breaks incremental rebuilds

Medium Severity

binderRef and kernelName are stored via .Page.Scratch.Set in the shortcode and read via .Scratch.Get in baseof.html, while hasThebe correctly uses .Page.Store. In Hugo, .Scratch values are reset on incremental rebuilds (e.g., during hugo server when editing layout files), but .Store values persist. This means hasThebe will be true (rendering the entire Thebe script block), but binderRef will be empty, so the {{ if $binderRef }} guard skips setting window.thebeBinderRef, causing the JavaScript to early-return at the missing-binder check and silently disable all interactive functionality.

Additional Locations (2)

layouts/shortcodes/jupyter-example.html#L50-L51

layouts/_default/baseof.html#L57-L59

cursor · 2026-03-18T14:24:33Z

layouts/shortcodes/jupyter-example.html

+    {{ end }}
+
+    <script type="text-x-clean-source" style="display:none">{{ $stepCode | safeHTML }}</script>
+    <script type="text-x-full-file-source" style="display:none">{{ $fullFileCode | safeHTML }}</script>


Using safeHTML in script tags risks HTML breakage

Medium Severity

The safeHTML pipe inside <script> elements means source code containing </script> (e.g., a Python string like html = "</script>") would prematurely close the tag and break the page HTML. Since <script> content is raw text, HTML entity escaping doesn't work either—a different encoding strategy (like base64 or escaping </ sequences) is needed to safely embed arbitrary source code.

cursor · 2026-03-18T14:24:33Z

layouts/_default/baseof.html

+                const stepLines = lines.slice(currentStepRange.start, currentStepRange.end + 1);
+                stepCode = stepLines.join('\n');
+              }
+            }


Stale line ranges after user edits step code

Low Severity

The lineRanges JSON is static (computed at build time), but CodeMirror content is dynamic. If a user adds or removes lines within the editable step section while in expanded view, lines.slice(currentStepRange.start, currentStepRange.end + 1) extracts incorrect code—either truncating added lines or including lines from adjacent sections. This affects both execution and the collapse toggle in toggleJupyterVisibility.

Additional Locations (1)

layouts/shortcodes/jupyter-example.html#L605-L613

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 5 total unresolved issues (including 3 from previous reviews).

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

cursor · 2026-03-18T14:47:50Z

layouts/shortcodes/jupyter-example.html

+{{ $noOutput := .Get "no_output" | default "false" }}
+{{ $quickstartUrl := .Get "quickstart_url" | default "" }}
+{{ $quickstartTitle := .Get "quickstart_title" | default "" }}
+{{ $inner := .Inner | default "" }}


Unused $inner and $hlLines variables are dead code

Low Severity

$inner (from .Inner) is assigned but never referenced anywhere in the template. Similarly, $hlLines, $currentStepStartLine, and $currentStepEndLine are computed but never used in the template output. These are dead code that adds confusion about the template's intent.

Additional Locations (1)

layouts/shortcodes/jupyter-example.html#L239-L243

cursor · 2026-03-18T14:47:50Z

.github/workflows/main.yml

      run: make deps

+    - name: Generate components
+      run: make components


Missing make components in setup_and_build_latest CI job

High Severity

The make components step was added to the matrix build jobs (kubernetes, rs, rdi, redisvl), but NOT to the setup_and_build_latest job which also builds the latest docs — including the redis-py page that now contains jupyter-example shortcodes. That shortcode calls errorf if data/examples.json (generated by make components) is missing, so the setup_and_build_latest job will fail at Hugo build time.

paoloredis requested review from andy-stark-redis, dwdougherty and mich-elle-luna March 17, 2026 14:19

cursor bot reviewed Mar 17, 2026

View reviewed changes

layouts/_default/baseof.html Outdated Show resolved Hide resolved

layouts/shortcodes/jupyter-example.html Show resolved Hide resolved

dwdougherty approved these changes Mar 17, 2026

View reviewed changes

cursor bot reviewed Mar 17, 2026

View reviewed changes

layouts/shortcodes/jupyter-example.html Outdated Show resolved Hide resolved

andy-stark-redis requested changes Mar 17, 2026

View reviewed changes

content/develop/clients/redis-py/_index.md Outdated Show resolved Hide resolved

cursor bot reviewed Mar 17, 2026

View reviewed changes

layouts/_default/baseof.html Show resolved Hide resolved

layouts/shortcodes/jupyter-example.html Outdated Show resolved Hide resolved

cursor bot reviewed Mar 18, 2026

View reviewed changes

paoloredis added 7 commits March 18, 2026 15:14

First interactive code example

5782890

Hide KERNEL_NAME from code cell

42c842d

Fix selector mismatch

e91ad68

Remove unused variable

bfb7944

Use eq instead of hasPrefix

27e4055

Use explicit self-closing

4a0d800

Drive shortcode config via data/examples.json as much as possible

3adb358

paoloredis force-pushed the DOC-6375 branch from 2ed1296 to 3adb358 Compare March 18, 2026 14:14

cursor bot reviewed Mar 18, 2026

View reviewed changes

Make components in build to generate examples.json before build

0bd9a00

cursor bot reviewed Mar 18, 2026

View reviewed changes

Conversation

paoloredis commented Mar 17, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 17, 2026 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 17, 2026

Uh oh!

jit-ci bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛡️ Jit Security Scan Results

Uh oh!

Uh oh!

Uh oh!

dwdougherty left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

andy-stark-redis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mich-elle-luna commented Mar 17, 2026

Uh oh!

cursor bot Mar 18, 2026

Choose a reason for hiding this comment

Scratch vs Store inconsistency breaks incremental rebuilds

Uh oh!

cursor bot Mar 18, 2026

Choose a reason for hiding this comment

Using safeHTML in script tags risks HTML breakage

Uh oh!

cursor bot Mar 18, 2026

Choose a reason for hiding this comment

Stale line ranges after user edits step code

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Mar 18, 2026

Choose a reason for hiding this comment

Unused $inner and $hlLines variables are dead code

Uh oh!

cursor bot Mar 18, 2026

Choose a reason for hiding this comment

Missing make components in setup_and_build_latest CI job

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

paoloredis commented Mar 17, 2026 •

edited by cursor bot

Loading

github-actions bot commented Mar 17, 2026 •

edited by atlassian bot

Loading

jit-ci bot commented Mar 17, 2026 •

edited

Loading

Using `safeHTML` in script tags risks HTML breakage

Unused `$inner` and `$hlLines` variables are dead code

Missing `make components` in setup_and_build_latest CI job