Reveal.js Debugging

Use this skill when working on a Reveal.js deck and any of the following happens:

• a slide is blank even though its content exists
• vertical or nested slides behave strangely
• fragments or present slides exist in the DOM but are not visible
• navigation works, but slide layout is broken
• custom CSS appears to break slide positioning

Load alongside

For browser inspection and live page debugging, also load:

• ../chrome-devtools-cli/SKILL.md

Use the Chrome DevTools CLI via bash to inspect the current deck in the browser.

Core lessons

1. Be very careful styling framework-owned section elements

Reveal.js controls slide layout using its own positioning rules on slide sections. A broad rule like this can break nested or vertical slides:

css
1.reveal .slides section {
2  position: relative;
3}

This can cause active slides to render off-screen while still existing in the DOM and accessibility tree.

Prefer styling an inner wrapper instead, for example:

css
1.theme-shell {
2  position: relative;
3  height: 100%;
4}

Rule of thumb:

• avoid overriding layout-critical properties on .reveal .slides section
• put custom positioning on your own inner container like .theme-shell or .slide-frame

2. Snapshot presence does not guarantee visual correctness

A Reveal.js slide can:

• appear in the accessibility snapshot
• contain the right text in the DOM
• still be visually off-screen or invisible

So use both:

• take_snapshot to confirm semantic presence
• take_screenshot to confirm actual rendering

3. Computed layout is often the fastest signal

If a slide is blank, inspect:

• .slides section.present
• .slides > section.present
• .slides > section > section.present

Check:

• getBoundingClientRect()
• position
• top / left
• display
• transform
• whether the active slide rect is inside the viewport

A strong clue is: the slide is present, but its rect has a large y value outside the viewport.

Fast debugging workflow

1. Open the current deck in Chrome DevTools CLI

bash
1chrome-devtools list_pages
2chrome-devtools select_page <pageId>
3chrome-devtools take_snapshot

2. Navigate to the broken slide

Use Reveal controls or keyboard:

bash
1chrome-devtools press_key "ArrowRight" --includeSnapshot true
2chrome-devtools press_key "ArrowDown" --includeSnapshot true

3. Compare semantic vs visual state

bash
1chrome-devtools take_snapshot
2chrome-devtools take_screenshot --fullPage true --filePath "/tmp/reveal-debug.png"

If the snapshot shows content but the screenshot is blank, suspect CSS/layout rather than data/content loading.

4. Inspect active slide geometry

bash
1chrome-devtools evaluate_script '() => ({
2  present: Array.from(document.querySelectorAll(".slides section.present")).map(el => {
3    const r = el.getBoundingClientRect();
4    const s = getComputedStyle(el);
5    return {
6      cls: el.className,
7      text: (el.innerText || "").slice(0, 120),
8      rect: { x: r.x, y: r.y, w: r.width, h: r.height },
9      position: s.position,
10      top: s.top,
11      left: s.left,
12      display: s.display,
13      transform: s.transform,
14      opacity: s.opacity,
15      visibility: s.visibility
16    };
17  })
18})'

5. Inspect suspicious CSS

Look for broad selectors affecting Reveal internals, especially:

• .reveal .slides section
• .reveal section
• section
• .stack
• .present

Common dangerous properties:

• position
• display
• transform
• overflow
• height
• min-height
• top / left

Known good pattern

Use Reveal-managed sections for slide structure and your own wrapper for layout:

html
1<section class="theme-shell">
2  <div class="slide-frame">
3    <h2>Title</h2>
4  </div>
5</section>

css
1.reveal .slides section {
2  box-sizing: border-box;
3}
4
5.theme-shell {
6  position: relative;
7  height: 100%;
8}

Practical heuristic

If Reveal.js looks broken:

1. suspect CSS before JavaScript
2. verify the active slide exists with snapshot/DOM inspection
3. verify it is actually in the viewport with getBoundingClientRect()
4. remove or narrow any global section rules
5. move custom layout onto inner wrapper elements