Comprehensive Prompt: Fixing Missing Interactive Elements on Deployed Quarto Website

Problem Statement

I have a Quarto website (quarto-website) with a case study page (projects/case_study_web.qmd) that contains multiple interactive visualizations and dashboards. The page renders correctly locally with all interactive elements working, but when deployed to the live website (https://mdastgheib.com/projects/case_study_web.html), several critical elements are missing or broken:

Missing/Broken Elements on Deployed Site:

  1. Interactive Dashboard: “Results Dashboard: Interactive comparison of key metrics by modality” - not displaying
  2. Interactive Error Type Plot: “Error Type Composition by Modality (interactive stacked bar)” - not displaying
  3. Interactive Heatmaps:
    • Endpoint Density Heatmap (Static and Adaptive variants)
    • Spatial Error Rate Heatmap (Hand and Gaze modalities)
  4. Static Images: Some fallback images may not be loading correctly
  5. CSV Data Tables: Results tables that depend on CSV files may not be rendering

What Works Locally:

  • All interactive Highcharter plots render correctly
  • All static fallback images display
  • All CSV-based tables render properly
  • All JavaScript interactions work (hover, zoom, pan)

Current Configuration

File Structure:

quarto-website/
├── _quarto.yml (website config)
├── projects/
│   └── case_study_web.qmd (the problematic file)
├── docs/
│   └── assets/
│       └── case_study/
│           ├── *.csv (data files)
│           └── portfolio/
│               └── *.png (static images)
└── _site/ (output directory)
    └── projects/
        └── case_study_web.html

Current QMD File Settings (case_study_web.qmd):

format:
  html:
    embed-resources: false
    self-contained: false
    lightbox: true

Interactive Elements in the QMD File:

  1. Results Dashboard (results-dashboard-interactive chunk):
    • Uses highcharter library
    • Creates grouped column chart comparing metrics by modality
    • Has fallback to static results_dashboard.png image
  2. Error Type Composition (error-type-fig-interactive chunk):
    • Uses highcharter library
    • Creates stacked bar chart showing error type distribution
    • Has fallback to static error_type_composition.png image
  3. Endpoint Density Heatmaps (endpoint-heatmap-static, endpoint-heatmap-adaptive chunks):
    • Uses highcharter library
    • Creates interactive heatmaps with hover tooltips
    • Has fallback to static heatmap_endpoint_density.png image
  4. Spatial Error Heatmaps (spatial-heatmap-hand, spatial-heatmap-gaze chunks):
    • Uses highcharter library
    • Creates interactive heatmaps showing error rates by screen position
    • Has fallback to static heatmap_spatial_errors.png image

R Libraries Used:

  • highcharter (for interactive plots)
  • tidyverse (data manipulation)
  • knitr, kableExtra (tables)
  • gt (enhanced tables)

Questions & Requirements

1. JavaScript Library Loading (CRITICAL)

Question: How should Highcharter JavaScript libraries be included in the deployed HTML?

Current Problem: Highcharter plots require: - Highcharts.js (core library) - Highcharts modules (for specific chart types) - jQuery (dependency)

Options to consider: - Option A: Set embed-resources: true to embed all JavaScript inline - Pros: Everything works, no external dependencies - Cons: Larger file size, but acceptable for a single page

  • Option B: Set self-contained: true to create a single-file HTML
    • Pros: Single file, everything embedded
    • Cons: Very large file size
  • Option C: Manually add Highcharter CDN links in include-in-header or include-before-body
    • Pros: Smaller HTML file
    • Cons: Requires external CDN access, more complex setup
  • Option D: Use Quarto’s html-dependency system to properly declare Highcharter dependencies
    • Pros: Proper Quarto way, automatic handling
    • Cons: Need to understand Quarto’s dependency system

Which option is recommended for GitHub Pages deployment?

2. Resource Paths

Question: How should resource paths be configured for deployment? - Are image paths (images/*.png) resolving correctly on the deployed site? - Should CSV files be copied to _site/projects/ or referenced differently? - Do we need to configure base-url or other path settings in _quarto.yml?

3. Interactive Plot Fallbacks

Question: How should fallback static images be handled? - When interactive plots fail to load, should fallback images always be shown? - Are the current fallback mechanisms (if/else logic) sufficient? - Should we pre-render static versions of all interactive plots?

4. Data File Availability

Question: How should CSV data files be handled? - Should CSV files be copied to _site/projects/ during render? - Are CSV files accessible at the correct paths on the deployed site? - Should we use absolute URLs or relative paths?

5. Deployment Process

Question: What deployment steps are needed? - Should we run quarto render with specific flags? - Do we need to copy additional files/folders to _site/? - Are there post-render scripts needed to fix paths or copy resources?

6. Verification

Question: How can we verify everything works? - What checks should we perform on the local _site/ directory before deploying? - How can we test interactive elements locally in the rendered HTML? - What browser console errors should we look for?

Specific Technical Requirements

Required Outcome:

The deployed HTML file (https://mdastgheib.com/projects/case_study_web.html) should have:

  1. ✅ All interactive Highcharter plots working:
    • Results Dashboard with hover tooltips and zoom/pan
    • Error Type Composition stacked bar chart
    • Endpoint Density Heatmaps (both Static and Adaptive)
    • Spatial Error Heatmaps (both Hand and Gaze)
  2. ✅ All static images loading:
    • Task layout diagram
    • Architecture diagram
    • Participant journey diagram
    • Psychophysics diagram
    • All fallback images for interactive plots
  3. ✅ All data tables rendering:
    • Results table from results_at_a_glance.csv
    • Error type breakdown table from error_types_by_modality.csv
    • QC exclusions summary table
  4. ✅ All CSV data accessible:
    • CSV files should be readable by R chunks during render
    • CSV files should be accessible if needed client-side

Constraints:

  • Must work with GitHub Pages or similar static hosting
  • Must not require server-side processing
  • Should maintain reasonable page load times
  • Should work across modern browsers

Expected Deliverables

Please provide:

  1. Exact configuration changes needed in:
    • projects/case_study_web.qmd (YAML frontmatter and/or chunk options)
    • _quarto.yml (if website-level changes needed)
  2. Step-by-step deployment checklist:
    • Pre-render steps
    • Render command(s) with exact flags
    • Post-render file copying/fixing steps
    • Verification steps
  3. Code fixes (if needed):
    • Updates to R chunks to ensure proper resource handling
    • Path corrections for images, CSVs, and JavaScript libraries
    • Fallback logic improvements
  4. Verification script or commands:
    • How to test locally that everything will work when deployed
    • What to check in browser DevTools
    • Expected file structure in _site/ directory
  5. Troubleshooting guide:
    • Common issues and solutions
    • How to debug missing interactive elements
    • How to verify JavaScript libraries are loading

Current Status

  • ✅ Local rendering works perfectly
  • ✅ All files exist in correct locations
  • ✅ R code executes without errors
  • ❌ Deployed site missing interactive elements
  • ❌ CRITICAL FINDING: Highcharter JavaScript libraries are NOT being included in the rendered HTML
  • ❌ When embed-resources: false and self-contained: false, Quarto does not automatically include Highcharter’s JavaScript dependencies
  • ❌ Resource paths may be incorrect

Root Cause Analysis

Primary Issue: The QMD file has:

embed-resources: false
self-contained: false

This means: - JavaScript libraries (like Highcharter) are NOT embedded in the HTML - External resources are NOT bundled - The HTML file relies on external CDN links that may not be present

Verification: Checking the rendered HTML shows: - ✅ Quarto’s own JavaScript libraries are included (quarto-nav.js, quarto.js, etc.) - ❌ Highcharter JavaScript libraries are MISSING - ❌ No <script> tags for Highcharts.js or Highcharter dependencies

Why it works locally: When viewing locally with quarto preview, Quarto may be serving additional resources that aren’t included in the static HTML file.

Additional Context

  • Website URL: https://mdastgheib.com
  • Case Study Page: https://mdastgheib.com/projects/case_study_web.html
  • Repository: quarto-website (GitHub)
  • Deployment: Likely GitHub Pages or similar static hosting
  • Quarto Version: (check with quarto --version)

Goal: Achieve 100% parity between local rendered HTML and deployed HTML, ensuring all interactive plots, images, tables, and data files work correctly on the live website.

Back to top