Layout Engine & Metrics

Relevant source files

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

• packages/markdowndeck/src/markdowndeck/layout/constants.py
• packages/markdowndeck/src/markdowndeck/layout/init.py
• packages/markdowndeck/src/markdowndeck/visualization/renderer.py
• packages/markdowndeck/README.md
• packages/markdowndeck/src/markdowndeck/parser/directive/directive_parser.py
• tests/markdowndeck/integration/test_pipeline_contracts.py

The Layout Engine & Metrics system is the spatial reasoning core of the MarkdownDeck library. It is responsible for transforming abstract Markdown elements into precise, coordinate-based objects suitable for the Google Slides API. The engine follows a "Blank Canvas First" architecture, calculating the ideal position and size for every element—including titles, text blocks, images, tables, and nested sections—while strictly adhering to a set of predefined typographic and spacing metrics.

This module acts as a pure spatial planner within a four-stage conversion pipeline. It receives an unpositioned Deck object from the Parser and outputs a "Positioned" Slide object. While the engine identifies content overflow by placing elements beyond slide boundaries, it is intentionally "overflow-blind," leaving the resolution of these overflows to a dedicated downstream manager.
Sources: packages/markdowndeck/README.md:46-63, packages/markdowndeck/src/markdowndeck/layout/init.py:18-30

Architecture and Core Components

The layout architecture is orchestrated by the LayoutManager, which utilizes a PositionCalculator to execute the actual coordinate math. The engine operates on a hierarchy of zones (Header, Body, Footer) and recursive sections.

Data Flow for Layout Calculation

The following diagram illustrates how the LayoutManager processes a slide through the positioning pipeline.

The engine first establishes the "Max Content Area" by subtracting margins from the default slide dimensions (720x405 points). It then analyzes images for proactive scaling before delegating to the PositionCalculator to assign (x, y) coordinates and (width, height) dimensions to every renderable element.
Sources: packages/markdowndeck/src/markdowndeck/layout/init.py:32-72, packages/markdowndeck/src/markdowndeck/layout/constants.py:126-127

Layout Zones and Spacing Metrics

The layout engine divides each slide into three primary vertical zones. These zones provide the high-level containers for all content.

Zone Dimensions

Zone Name	Height (Points)	Purpose
Header	90.0	Reserved for H1 titles and H2 subtitles.
Body	Dynamic	The primary content area for sections, lists, and images.
Footer	30.0	Reserved for slide-level footer text.

Sources: packages/markdowndeck/src/markdowndeck/layout/constants.py:7-9, packages/markdowndeck/src/markdowndeck/visualization/renderer.py:53-73

Spacing Principles

The engine adheres to a "Zero Default Spacing" principle, where inter-zone gaps and default paddings are set to 0.0 unless specifically overridden by user directives. This allows for total programmatic control over the layout density.
Sources: packages/markdowndeck/src/markdowndeck/layout/constants.py:13-19

Typographic Metrics and Font Scaling

Typography is governed by a strict set of constants that define font sizes, line heights, and character width estimates used for text wrapping calculations.

Default Typographic Standards

Element Type	Font Size (pt)	Line Height Multiplier
H1 (Title)	24.0	1.2
H2 (Subtitle)	20.0	1.2
Paragraph (P)	14.0	1.4
Code Block	12.0	1.2
Footer	10.0	N/A

Sources: packages/markdowndeck/src/markdowndeck/layout/constants.py:27-44

To estimate bounding boxes for text before rendering, the engine uses character width estimates:

• Standard Text: 5.0 points per character.
• Monospace Text: 7.5 points per character.
• Title Text: 5.5 points per character.
  Sources: packages/markdowndeck/src/markdowndeck/layout/constants.py:47-49

Directive Processing and Override Logic

The layout engine integrates closely with the DirectiveParser to handle per-element or per-section layout overrides. Directives are parsed from Markdown (e.g., [width=1/2]) and converted into numeric values that the LayoutManager uses during its calculation pass.

Common Layout Directives

Directive	Valid Values	Metric Impact
width	Fractions (1/2), %, Pixels	Overrides calculated section/element width.
height	Fractions, %, Pixels	Overrides calculated section/element height.
padding	Numeric value	Adds internal space between element border and content.
gap	Numeric value	Explicit vertical spacing between adjacent elements.

Sources: packages/markdowndeck/src/markdowndeck/parser/directive/directive_parser.py:26-53, tests/markdowndeck/integration/test_pipeline_contracts.py:168-185

# Example of Directive Value Conversion in DirectiveParser
# File: packages/markdowndeck/src/markdowndeck/parser/directive/directive_parser.py:26-53
self.directive_types = {
    "width": "dimension",
    "height": "dimension",
    "align": "alignment",
    "padding": "dimension",
    "gap": "dimension",
    "fontsize": "dimension",
}

Minimum Dimensions and Safety Constants

To prevent elements from disappearing or causing calculation errors, the engine enforces minimum size thresholds and safety buffers.

• Absolute Minimum Height: 16.0 points for any visible element.
• Minimum Image Height: 100.0 points.
• Calculation Epsilon: 0.1 points (minimum meaningful dimension difference).
• Overflow Tolerance: 1000.0 points before a warning is triggered.
• Max Iterations: 100 (limit for recursive layout calculations).

Sources: packages/markdowndeck/src/markdowndeck/layout/constants.py:64-75, packages/markdowndeck/src/markdowndeck/layout/constants.py:143-145

Conclusion

The Layout Engine & Metrics system provides the deterministic spatial logic required to automate slide creation. By combining fixed typographic constants, rigid zone definitions, and flexible directive-based overrides, it ensures that Markdown content is translated into a structured visual format that respects both design constraints and content requirements.