Building Interactive Notebooks for EDS - A Journey in Context-Aware Design

When developing Adobe Edge Delivery Services blocks, developers face a familiar frustration: the feedback loop is too slow, with constant browser refreshes and console checks. However, this is the story of how I built a browser-based Jupyter notebook integration that transformed both our development workflow and how we share EDS knowledge through executable documentation.

The Challenge

When developing Adobe Edge Delivery Services (EDS) blocks, developers often face a common frustration: the feedback loop is too slow. Make a change, refresh the browser, check the console, repeat. Could we test blocks interactively, see the results immediately, and share executable examples with end-users?

This is the story of how we built a browser-based Jupyter notebook integration that runs entirely in the browser—no setup, no initialisation, no complexity. Simply click "Run" to view the results.

The Vision - Making Testing Accessible

We set out to solve a fundamental problem: how to make block testing and documentation interactive without requiring users to install tools or configure environments?

For Developers:

For End Users:

The solution? A pure browser-based system where Jupyter notebooks become interactive pages on your EDS site. No Node.js, no kernel selection, no initialisation - just click "Run" and see results.


Before we explain, do you want to see it live? https://allabout.network/blogs/ddt/integrations/live-version-of-the-ipynb-blog-post

The Technical Innovation - Zero Configuration

Most interactive notebook systems require setup steps, initialisation code, or environment configuration. We wanted something different - notebooks that just work. Open the page, click "Run," and view the results.

The breakthrough was realising we didn't need initialisation at all. Each code cell imports what it needs when it needs it. The browser already has everything - JavaScript execution, DOM manipulation, and the actual EDS blocks we want to test—no setup required.

The ipynb-viewer Block - The Heart of the System

The entire system centres on a single EDS block called ipynb-viewer. This block transforms static Jupyter notebook files into fully interactive, read-only experiences.

How It Works

When you add the ipynb-viewer block to a page, you simply reference a notebook file. The block fetches the notebook JSON, parses its structure, and renders it as an interactive document. Markdown cells become formatted content. Code cells become executable JavaScript with "Run" buttons.

The magic happens when users click "Run". The block executes the pre-written JavaScript code in the browser context, captures console output, displays return values, and shows results inline—all without any initialisation or setup steps.

Users experience the code running, but cannot edit it. This is by design - the notebooks serve as interactive demonstrations and tutorials, where users learn by running carefully crafted examples, rather than experimenting with modifications.

The Enhanced Markdown Parser

We built a comprehensive markdown parser specifically for EDS notebooks. It handles code blocks with syntax highlighting, properly formatted tables that can span multiple lines, ordered and unordered lists, inline formatting including bold, italic, code spans, and links, and headers at various levels.

The parser processes content carefully to avoid conflicts. It extracts code blocks first and replaces them with placeholders. Then it parses tables across multiple lines. Headers come next, followed by inline formatting. Finally, it restores the code blocks and converts line breaks.

This ordering matters because markdown syntax can overlap. A table cell might contain inline code. A list item might have bold text. The parser handles these nested cases gracefully.

Interactive Code Execution

Each code cell displays a "Run" button prominently placed. When clicked, the block executes the JavaScript using the browser's native eval mechanism wrapped in async/await support. Console output is captured, including both regular logs and errors. Return values display automatically. Visual indicators show whether execution succeeded or failed.

The execution happens in the page's context, which means the code has access to all the EDS blocks, styles, and utilities. Users aren't testing in an isolated sandbox - they're experiencing the real environment where blocks actually run.

The Import-as-Needed Pattern

The key innovation that eliminated initialisation is the import-as-needed pattern. Each code cell imports exactly what it needs, exactly when it needs it.

A cell testing block imports the testBlock function. A cell showing previews imports the showPreview function. A cell demonstrating pure JavaScript imports nothing; it simply runs.

This pattern means cells are entirely independent. Users can run them in any order. They can run the same cell multiple times. They can skip cells they're not interested in. There's no "run this first" requirement because each cell is self-contained.

Testing Blocks Without Complexity

The real power emerges when you test EDS blocks. Write a Markdown cell explaining what you're testing. You write a code cell that imports the test helper, creates content, and runs the test. Users click "Run" and immediately see the transformation.

No initialisation needed. No environment setup. No kernel selection. Just click and see results.

A Real Example - Simple DOM Test

The simplest test creates a fundamental DOM element. The code creates a div, sets its text content, adds some styling with inline CSS, logs the result, and returns the HTML. Users click "Run" and see the styled element appear in the output area. The console shows confirmation that the component was created.

This proves the browser environment works. The system can create elements, style them, and display results. Everything needed for demonstrations is right there.

Testing Block Transformation

The next level tests actual blocks. The code imports the testBlock helper function. It creates content in the EDS table format - nested divs with test data. It calls testBlock with the block name and content. It returns the resulting HTML.

Users click "Run" and watch the transformation happen. The output shows the decorated block. Console logs confirm the block loaded and ran successfully. They see exactly what the block did to the content.

Before and After Comparison

A particularly effective pattern shows before and after states. The code creates an element with test content and captures its HTML. It runs the block decoration and captures the resulting HTML. It returns a formatted string showing both states plus a summary of what changed.

For an accordion block, the output might show "BEFORE: 2 divs → AFTER: 2 details". Users see the actual HTML structure in both states. The transformation becomes crystal clear.

The Overlay Preview System

The most impressive feature is the preview overlay. Instead of opening popup windows or new tabs, previews appear as overlays on the same page.

The code imports the showPreview function. It defines test content. It calls showPreview with the block name and content. Users click "Run" and the function creates a full-page overlay with the block fully styled and interactive.

The overlay includes everything - core EDS styles, block-specific CSS, proper DOM structure, and working JavaScript. The block decorates automatically and appears exactly as it would on a real page. Users can interact with it by clicking accordion sections, navigating carousels, or performing any other action the block supports.

Press ESC or click outside the overlay to make it disappear. Rerun the cell, and the preview reappears. Multiple preview calls replace the previous overlay, eliminating the need for window management.

Edge Case Testing

The next cells test edge cases. What happens with empty content? Users run the cell and see how the block handles it gracefully. What about a single item? The test shows whether navigation appears. What about 50 items? The test runs and displays performance metrics.

Each test is self-contained. Each has an explanation in markdown, executable code, and visible results. Users learn by seeing fundamental transformations in action, not just reading descriptions.

Pure JavaScript Examples

The system works beautifully for pure JavaScript examples as well. No block testing required - just demonstrate JavaScript concepts.

One cell performs calculations, adding numbers, multiplying them, and computing averages. Users click "Run" and see the results. Console output shows each step. The return value displays the final result.

Another cell demonstrates array operations. Create an array, map over it to double values, and reduce it to a sum. The console shows each transformation. The output displays the doubled array.

Text transformations work the same way. Convert strings to uppercase, title case, or any other format. Each transformation logs to the console and displays results.

This makes notebooks perfect for teaching JavaScript basics alongside EDS concepts. Users learn language fundamentals in the same environment where they'll see them applied.

The Development Workflow

This browser-based approach transformed our development workflow in unexpected ways.

Creating Interactive Demonstrations

Instead of writing static documentation, you create interactive demonstrations. You write markdown explaining a concept. You write code that demonstrates it. You publish the notebook. Users click "Run" and see the idea in action.

The cycle time collapsed. What used to take hours to document now takes minutes to demonstrate. You're always one click away from showing how something works.

Living Documentation

The notebooks became living documentation. Every example runs. Every test executes. Documentation can't become outdated because, if it works, it will continue to run. If it doesn't run, you know immediately.

This changes how teams share knowledge. Instead of writing "this block works like this", you write "click Run to see how this block works". The difference is profound.

Teaching Through Interaction

We discovered the system works brilliantly for teaching. New developers learn EDS by running examples, not just reading about them. They see what happens when code executes. They experience transformations in real-time.

Tutorial notebooks walk users through concepts step by step. Each cell builds on the previous one. Users run each step and see the progression. They understand not just what happens but why it happens.

Using Claude to Create Interactive Notebooks

Here's where the workflow becomes truly powerful. Claude can create comprehensive notebook content in minutes, and because everything runs in the browser with no initialisation, there's no setup complexity to explain.

The Foundation - Skills and Documentation

The system relies on comprehensive EDS documentation that Claude can reference. This includes block architecture patterns, content structure requirements, testing methodologies, and real-world examples.

Adobe's EDS Skills for Claude provide workflow patterns. My docs/for-ai documentation provides implementation details. Together, they enable Claude to generate production-ready notebook content.

Natural Language Notebook Creation

You describe what you want to teach or demonstrate, and Claude creates the notebook content.

Example - Creating a Tutorial: You tell Claude, "Create an interactive tutorial for the accordion block that shows basic usage, edge cases, and common patterns."

Claude generates markdown cells that explain accordion concepts, code cells with basic examples that import helpers as needed, cells that demonstrate edge cases (empty content, single item, deeply nested), cells that show common patterns and best practices, and explanatory text between each example.

The entire tutorial is ready to add to a notebook file. Users can run every example and see the results. They learn by watching transformations happen.

Example - Testing Scenarios: You ask Claude, "Create demonstrations for my carousel block covering different layouts and configurations."

Claude creates demonstration cells for a basic carousel with three slides, a carousel with 10 slides for performance, horizontal and vertical layouts, auto-play enabled and disabled, navigation dots shown and hidden, and lazy loading behaviour.

Each demonstration includes the proper HTML content structure, appropriate configuration settings, the import statement for helper functions, and explanations of what's being shown.

Example - Troubleshooting Guide: You tell Claude, "Create an interactive troubleshooting guide for common block problems."

Claude generates cells showing "my block appears as a colored box" with code demonstrating proper CSS linking, "content doesn't transform" with examples of correct DOM structure, "styles don't apply" with solutions using the proper path, and "block throws errors" with examples of proper error handling.

Each example is executable. Users run the problematic scenario, see the issue, then run the solution and see it fixed.

Understanding Block Patterns Automatically

Claude has learned EDS content patterns from the documentation. When you ask for accordion examples, Claude creates nested divs with questions and answers. For cards, it builds structures with images and text. For heroes, it makes proper headings and media pairings.

You don't specify these patterns. Claude knows them and applies the proper structure automatically. The generated content just works when users run it.

Claude also understands the import pattern. Each cell that requires helpers receives the corresponding import statement. Cells that don't need helpers remain clean. Claude knows which functions each demonstration requires and imports precisely those.

Iterative Content Development

You can iterate with Claude to refine notebook content.

You tell Claude the basic example works great, but users need to see nested content patterns. Claude adds a cell with a properly nested HTML structure, the correct import statement, and an explanation of nesting behaviour.

You ask if Claude can add performance measurement. Claude adds timing code that logs decoration duration, using console.time() and console.timeEnd ().

You request variations showing different themes or layouts. Claude creates cells for each variation with appropriate styling and configuration, each importing what it needs.

Advanced Content Scenarios

Claude can create sophisticated educational content when you need it.

Interactive Comparisons: You ask Claude to create a notebook comparing different block approaches. Claude generates cells showing approach A with its imports, code, and results, approach B with its imports, code, and results, a comparison table highlighting the differences, and recommendations for when to use each approach.

Users run both approaches and see the differences firsthand.

Progressive Enhancement: You tell Claude to create a tutorial that builds complexity gradually. Claude generates cells starting with a minimal viable example, adding basic styling, incorporating configuration options, handling edge cases, and implementing advanced features.

Each step runs independently with its own imports. Users can run cells in sequence to see the progression, or jump to specific examples that interest them.

Problem-Solution Patterns: You ask Claude to create content showing common problems and their solutions. Claude generates cells that demonstrate the problem with code that fails or produces incorrect output, an explanation of why it fails, the solution with corrected code and proper imports, and verification showing it now works correctly.

Users see the actual failure, understand the cause, and then witness the fix take effect.

The Prompt Patterns That Work Best

Through extensive use, specific prompt patterns work particularly well.

For tutorial content, you state "Create an interactive tutorial for [concept] that covers [topics] with proper imports in each cell". For demonstration scenarios, you say "Create demonstrations for [block] covering [scenarios] with independent cells". For troubleshooting, you request "Show common problems with [block] and their solutions as executable cells". For comparisons, you ask, "Compare [approach A] and [approach B] with working examples that import helpers as needed". For progressive learning, you specify "Build a tutorial from basic to advanced [concept] where each cell stands alone".

Real Example - Complete Session

Here's a real session showing Claude creating notebook content.

You ask Claude to create interactive content for teaching the carousel block to new developers, emphasising that cells should be independent demonstrations.

Claude generates a markdown cell introducing carousels and their uses. A code cell with imports and a basic 3-slide example. Another markdown cell explaining navigation options. Code cells demonstrating dots navigation, arrow navigation, and auto-play - each importing helpers. A markdown cell covering edge cases. Code cells for single slide handling and empty content - again with imports. A markdown cell about performance. A code cell with 50 slides and timing measurement. Finally, a markdown cell summarising key points.

You tell Claude that users found the auto-play example unclear. Claude revises that cell, adding more explanation, breaking the configuration into steps, showing the effect of each setting, and ensuring the imports are clear.

You ask Claude to add content about accessibility. Claude adds markdown explaining ARIA requirements and code cells demonstrating proper ARIA labels, keyboard navigation support, and screen reader compatibility - each cell with necessary imports.

Total time: About 5 minutes. Result: Complete interactive tutorial ready for users, with no initialisation required.

Why This Works So Well

The combination makes this system special.

Claude understands EDS patterns, so content follows proper structures automatically. Claude knows the import pattern, so each cell gets precisely what it needs. Examples work on the first try because Claude has seen hundreds of working examples. Edge cases are included because Claude is aware of common pitfalls. Explanations are clear because they're based on proven teaching approaches. Everything runs in the browser with no setup, so users need nothing beyond a browser. The read-only design means users focus on learning from examples rather than experimenting with modifications.

Getting Claude Set Up

To enable Claude to create notebook content for your blocks, you add the Jupyter testing documentation to your project. Claude reads this and understands the patterns, including the import-as-needed approach and the read-only nature of the viewer.

You describe your blocks to Claude - their names, what they do, and typical content structures. Claude generates appropriate demonstrations, each cell complete with its necessary imports.

The Time Savings

Creating notebook content manually requires a significant amount of time. You spend 30 minutes planning content flow, 45 minutes writing examples and demonstrations, 15 minutes adding proper imports to each cell, 20 minutes creating explanations, 15 minutes testing everything works, and 20 minutes debugging issues. Total: around 2 hours and 25 minutes per notebook.

Creating notebook content with Claude takes dramatically less time. You spend 3 minutes describing what you want and 5 minutes reviewing the content. Total: around 8 minutes per notebook.

That's a massive time reduction. Better tools really do make better developers.

Publishing Interactive Notebooks

Getting your notebook onto your EDS site is straightforward. Create your notebook file - either manually or with Claude's help. Save it with an ipynb extension. Upload it to your site repository.

In a Google Doc, add the ipynb-viewer block. Create a table with "IPynb Viewer" in the first cell and the path to your notebook file in the second cell. Publish the page.

That's it. Your notebook is now interactive on your site. Users can read explanations, click "Run" on code cells, see results inline, and learn by watching examples execute.

No installation instructions for users. No "download this tool" or "configure that environment". No "run this cell first to initialise". Just visit the page and start learning. Click any cell, in any order, and it works.

The CSS Workflow Innovation

One aspect that proved particularly elegant is how styling works. When code cells generate previews, those previews appear as overlays with all styles properly loaded—core EDS styles, block-specific CSS, and fonts all work seamlessly.

This creates a brilliant demonstration workflow. You write a demonstration cell that shows a styled block. Users click Run. The overlay appears with full styling. They press ESC to close it, then can rerun it to see it once more.

No file management. No regeneration. Just click and see - exactly what interactive documentation should be.

The Development Workflow Today

Our approach to creating block documentation underwent a complete transformation.

You create a notebook file—or ask Claude to make it. You add markdown cells explaining what you're demonstrating. You add code cells with examples, each importing what it needs. You publish the notebook to your site. Users open it in a browser. They run any cell, in any order, and see results immediately. You iterate on your demonstrations based on feedback. You share the notebook with your team and users as living, interactive documentation.

The speed difference is remarkable. What used to take an hour now takes minutes. The documentation process collapsed from "write, screenshot, explain" to "write code, publish, done".

Real-World Impact

The system proved its worth in unexpected ways.

Onboarding New Developers

New team members learn EDS through interactive notebooks. They don't just read about blocks - they watch them run. They see transformations happen in real-time. They learn by experiencing examples in a safe, read-only environment.

The learning curve shortened dramatically. What used to take a week now takes a day. New developers understand concepts faster.

Documentation That Stays Current

Our documentation can't become outdated because if the examples run, they work. When we update a block, we run the notebook. If demonstrations fail, we update them. Documentation and code stay synchronised automatically.

This eliminated the "documentation drift" problem, where examples stop working but nobody notices until a confused developer asks why nothing works.

Interactive Bug Reports

Team members report bugs by creating notebook cells that reproduce the issue. They show the input, the expected output, and the actual output. Other developers run the cell and immediately see the bug.

This eliminated the "works on my machine" problem. If the notebook shows the bug, everyone sees the bug. No ambiguity.

Client Demonstrations

We demonstrate block capabilities to clients using notebooks. We provide a basic example, run it, and then present more complex examples. Clients see real code producing real results. They understand capabilities immediately.

This transformed client conversations. Instead of "this block can do X", we say "let me show you". Click, results appear. Much more convincing.

The Honest Limitations

This system works remarkably well for most purposes, but there are limitations to be aware of.

What the System Can't Do: Users cannot modify code - notebooks are read-only demonstrations. Network requests don't work without CORS configuration. Some browser APIs have security restrictions. Heavy computational tasks slow the browser. Debugging tools are limited compared to developer consoles.

What the System Excels At: Demonstrating block functionality works perfectly. Showing block decoration logic thoroughly, verifying content structure transformations instantly, and displaying different configurations clearly, while providing immediate visual feedback through the overlay and teaching through interactive examples.

The key is understanding what each tool does best. Interactive notebooks excel at demonstrating, teaching, and showing how things work. Traditional developer tools excel at experimentation, deep debugging, and performance profiling. Use each where it shines.

Building This With AI

I built this browser-based notebook system using Claude, leveraging Adobe's Skills for Claude and my documentation for AI. The combination of workflow patterns and implementation knowledge enabled rapid development.

The result is simpler than initially imagined. By eliminating initialisation and letting each cell import what it needs, we removed all setup complexity. By making notebooks read-only, we focused users on learning from examples rather than experimenting with modifications. Users need no installation, no configuration, no "run this first" instructions. They just visit a page and start learning.

Key Innovations: The ipynb-viewer block handles everything automatically. No initialisation required - cells import what they need. Browser-native execution uses the real environment. The overlay system displays styled previews without requiring you to leave the page. CSS loads automatically with proper paths. Read-only design focuses users on learning from examples. Claude integration enables fast content creation and generates accurate imports for each cell.

The repository at github.com/ddttom/webcomponents-with-eds contains working examples, including the explain.ipynb notebook, the ipynb-viewer block implementation, helper utilities with the import functions, and comprehensive documentation.

Conclusion

Building this browser-based notebook system taught us that the best solutions remove complexity rather than managing it. By making everything run in the browser and eliminating initialisation, we removed every barrier to entry. By making notebooks read-only, we created focused learning experiences where users learn from carefully crafted examples.

The result is simpler, faster, and more accessible. Developers create demonstrations without setup. Users learn without installation. Documentation stays current automatically. Knowledge sharing becomes natural. Each cell stands alone, so users run what they need, when they need it.

The key innovations - browser-native execution, the ipynb-viewer block, import-as-needed pattern, overlay previews, proper path handling, read-only design, and Claude integration - combine to create something genuinely worthwhile. A system that developers want to use for creating demonstrations that learners can access without any barriers.

Whether you're demonstrating a complex block or teaching EDS to newcomers, the same notebooks work beautifully. Run any cell, in any order, and it just works. And with Claude's help, you can create comprehensive content in minutes, rather than hours, with proper imports in every cell. That's the power of removing unnecessary complexity.

The best tools disappear. Users don't think about the system - they think about what they're learning. That's what we've built here.

/fragments/ddt/proposition
style
bg-dark

Related Articles

Back to Top