Overflow Detection & Handling

Relevant source files

The following files were used as context for generating this wiki page:

• packages/markdowndeck/src/markdowndeck/overflow/detector.py
• packages/markdowndeck/src/markdowndeck/overflow/handlers.py
• packages/markdowndeck/src/markdowndeck/overflow/manager.py
• packages/markdowndeck/src/markdowndeck/overflow/init.py
• packages/markdowndeck/src/markdowndeck/overflow/constants.py
• packages/markdowndeck/src/markdowndeck/layout/constants.py
• packages/markdowndeck/src/markdowndeck/overflow/slide_builder.py

The Overflow Detection & Handling system is an enterprise-grade recursive content distribution engine within the MarkdownDeck library. Its primary purpose is to manage content that exceeds the physical boundaries of a Google Slide. It operates as the third stage of the MarkdownDeck pipeline, consuming "Positioned" slides from the layout calculator and producing a list of "Finalized" slides where content is intelligently partitioned.

The system adheres to strict jurisdictional boundaries, meaning it only triggers when a section's external bounding box overflows the available slide height. It specifically ignores internal content overflow within sections that have user-defined fixed sizes, ensuring that layout directives are respected while maintaining content visibility across multiple slides.

Sources: packages/markdowndeck/README.md, packages/markdowndeck/src/markdowndeck/overflow/init.py:7-22

Architectural Overview

The system is organized into four primary components that coordinate to detect, partition, and rebuild slide content. It follows a "Unanimous Consent" model for complex layouts like rows and columns, ensuring structural integrity is preserved across continuation slides.

Key Components

Component	Responsibility
OverflowManager	Main orchestrator that manages the iteration loop and slide finalization.
OverflowDetector	Analyzes slides to identify if the root_section exceeds the body_end_y boundary.
StandardOverflowHandler	Implements partitioning logic, including Rule A (Element Splitting) and Rule B (Unanimous Consent).
SlideBuilder	Constructs continuation slides, applying "(continued)" suffixes and resetting positions.

Sources: packages/markdowndeck/src/markdowndeck/overflow/manager.py:15-26, packages/markdowndeck/src/markdowndeck/overflow/detector.py:11-20, packages/markdowndeck/src/markdowndeck/overflow/handlers.py:12-25

Overflow Detection Logic

The detection phase enforces strict jurisdictional boundaries. It calculates a dynamic "body area" by accounting for the slide's top margin, the height of the title element (if present), and the footer area.

Jurisdictional Boundaries

A section is considered overflowing only if its section_bottom (top position + height) is greater than the calculated body_end_y. However, overflow is deemed "acceptable" and ignored if the section has an explicit [height] directive, as this indicates a user-defined fixed size.

Sources: packages/markdowndeck/src/markdowndeck/overflow/detector.py:22-55, packages/markdowndeck/src/markdowndeck/overflow/detector.py:83-91

Body Boundary Calculation

def _calculate_body_boundaries(self, slide: "Slide") -> tuple[float, float]:
    top_offset = self.top_margin
    bottom_offset = DEFAULT_MARGIN_BOTTOM
    title = slide.get_title_element()
    if title and title.size and title.position:
        top_offset = title.position[1] + title.size[1] + HEADER_TO_BODY_SPACING
    footer = slide.get_footer_element()
    if footer and footer.size and footer.position:
        bottom_offset = self.slide_height - footer.position[1]
    body_end_y = self.slide_height - bottom_offset
    return top_offset, body_end_y

Sources: packages/markdowndeck/src/markdowndeck/overflow/detector.py:57-79, packages/markdowndeck/src/markdowndeck/overflow/handlers.py:65-80

Partitioning Strategies

When overflow is detected, the StandardOverflowHandler partitions the root_section into a fitted_part and an overflowing_part.

Rule A: Element-Driven Splitting

For standard sections containing elements, the handler identifies the first element that crosses the available_height. It delegates the splitting decision to the element's own split() method.

• Splittable Elements: Text, Lists, Tables, and Code blocks.
• Atomic Elements: Images (effectively atomic as they are proactively scaled).

Sources: packages/markdowndeck/src/markdowndeck/overflow/handlers.py:108-144, packages/markdowndeck/src/markdowndeck/overflow/init.py:155-163

Rule B: Unanimous Consent Model

For row sections (multi-column layouts), the system uses a coordinated partitioning model. A row can only be split if all columns within that row consent to being split at the designated height.

Slide Finalization

The final step in the overflow process is converting the hierarchical section structure into a flat list of renderable_elements. This is handled by OverflowManager._finalize_slide.

1. Traversal: Recursively extracts elements from the root_section.
2. Deduplication: Uses object_id tracking to ensure elements aren't added twice.
3. Cleanup: Sets root_section to None and clears the elements list, transforming the slide into its final "Finalized" state ready for the API Request Generator.

Sources: packages/markdowndeck/src/markdowndeck/overflow/manager.py:68-105

Configuration and Constraints

The system includes safety limits to prevent infinite loops and excessive resource consumption.

Constant	Value	Description
MAX_OVERFLOW_ITERATIONS	50	Maximum attempts to process a single input slide.
MAX_CONTINUATION_SLIDES	25	Maximum number of slides a single input slide can produce.
CONTINUED_TITLE_SUFFIX	"(continued)"	Suffix added to continuation slide titles.
DEFAULT_SLIDE_HEIGHT	405.0	Standard 16:9 slide height in points.
HEADER_HEIGHT	90.0	Height reserved for the title zone.

Sources: packages/markdowndeck/src/markdowndeck/overflow/manager.py:11-12, packages/markdowndeck/src/markdowndeck/overflow/constants.py:4-18, packages/markdowndeck/src/markdowndeck/layout/constants.py:145-146

Summary

The Overflow Detection & Handling system ensures that complex Markdown layouts are reliably translated into professional presentations regardless of content length. By combining strict jurisdictional checks with an element-driven splitting model and unanimous row consent, it maintains both visual quality and structural integrity across multiple slides.