Element Builders & Models
Relevant source files
The following files were used as context for generating this wiki page:
- packages/markdowndeck/src/markdowndeck/parser/content/element_factory.py
- packages/markdowndeck/src/markdowndeck/parser/content/content_parser.py
- packages/markdowndeck/src/markdowndeck/parser/directive/directive_parser.py
- packages/markdowndeck/src/markdowndeck/visualization/renderer.py
- packages/markdowndeck/src/markdowndeck/layout/constants.py
- packages/google-workspace-mcp/src/google_workspace_mcp/utils/markdown_slides.py
The Element Builders & Models system forms the core data transformation layer of the MarkdownDeck library. It is responsible for translating raw Markdown tokens into structured, position-aware Python models that represent various slide components such as titles, text blocks, lists, tables, images, and code blocks. This system ensures that content is decoupled from its visual presentation, allowing for sophisticated layout calculations and multi-platform rendering.
The system operates through a factory pattern where a central ElementFactory produces specialized Element subclasses. These models store not only the raw content but also "directives"—metadata instructions that control visual attributes like color, alignment, and sizing.
Sources: packages/markdowndeck/src/markdowndeck/parser/content/element_factory.py:17-30, packages/markdowndeck/README.md
Architecture and Data Flow
The element creation process is part of a multi-stage pipeline. The ContentParser orchestrates the conversion by using markdown-it-py to tokenize text and then dispatching those tokens to various formatters which utilize the ElementFactory for model instantiation.
The diagram above illustrates how the ContentParser coordinates between directive parsing and element generation to create the final model suite used by the layout engine.
Sources: packages/markdowndeck/src/markdowndeck/parser/content/content_parser.py:35-50, packages/markdowndeck/src/markdowndeck/parser/content/element_factory.py:32-40
The Element Factory
The ElementFactory is the primary builder class. It assumes that directives have already been stripped from the text by the calling formatters or parsers, allowing it to focus strictly on model instantiation and inline formatting extraction.
Core Builder Methods
| Method | Target Element | Key Parameters |
|---|---|---|
create_title_element | ElementType.TITLE | title, formatting, directives |
create_text_element | ElementType.TEXT | text, formatting, alignment, directives |
create_list_element | ElementType.BULLET_LIST / ORDERED_LIST | items, ordered, directives |
create_table_element | ElementType.TABLE | headers, rows, directives |
create_image_element | ElementType.IMAGE | url, alt_text, directives |
create_code_element | ElementType.CODE | code, language, directives |
Sources: packages/markdowndeck/src/markdowndeck/parser/content/element_factory.py:42-125
Formatting Extraction
The factory includes an extract_formatting_from_text method. It utilizes the MarkdownIt parser to identify nested styles like Bold, Italic, Code, and Links. This method maps these styles to TextFormat objects with specific start and end indices relative to the plain text content.
Sources: packages/markdowndeck/src/markdowndeck/parser/content/element_factory.py:136-160
Directive Handling
Directives are specialized syntax blocks (e.g., [color=red]) that provide styling instructions. The DirectiveParser identifies these blocks, converts their values into appropriate types (dimensions, colors, or alignments), and associates them with the nearest element or section.
The DirectiveParser supports a wide range of keys, including width, height, align, background, and fontsize.
Sources: packages/markdowndeck/src/markdowndeck/parser/directive/directive_parser.py:20-60, packages/google-workspace-mcp/src/google_workspace_mcp/resources/slides.py:65-130
Layout and Dimension Models
Elements are governed by a set of constants that define their default visual properties when no directives are present. These are defined as a "Single Source of Truth" for the rendering engine.
Default Typography and Spacing
| Constant | Value | Description |
|---|---|---|
H1_FONT_SIZE | 24.0 | Main title font size |
P_FONT_SIZE | 14.0 | Paragraph text font size |
CODE_FONT_SIZE | 12.0 | Code block font size |
STANDARD_CHAR_WIDTH | 5.0 | Points per character for standard text |
LIST_INDENT_PER_LEVEL | 20.0 | Indentation per nesting level |
Sources: packages/markdowndeck/src/markdowndeck/layout/constants.py:32-45, packages/markdowndeck/src/markdowndeck/layout/constants.py:104-108
Rendering and Visualization
The models created by the factory are consumed by the renderer.py module. This module uses the position and size attributes—calculated during the layout phase—to draw the elements.
Rendering Logic Flow
- Validation: Checks if the element has a valid
position(x, y) andsize(w, h). - Style Resolution: Merges default constants with model-level directives.
- Dispatch: Calls type-specific renderers (e.g.,
_render_table,_render_image).
# Example of model data consumption in renderer
def _render_text(ax, element):
pos_x, pos_y = element.position
size_w, size_h = element.size
directives = getattr(element, "directives", {})
# ... style calculation ...
ax.text(text_x, text_y, content, fontsize=font_size, ...)
Sources: packages/markdowndeck/src/markdowndeck/visualization/renderer.py:112-145, packages/markdowndeck/src/markdowndeck/visualization/renderer.py:202-230
Summary
The Element Builders & Models system provides the structural foundation for turning Markdown into professional presentations. By separating the ElementFactory (creation logic), DirectiveParser (styling metadata), and Models (data structures), the project achieves a high degree of flexibility. This architecture allows the same Markdown content to be processed for different slide layouts, handled for overflow across multiple slides, and rendered to various formats like Google Slides API payloads or local visualizations.
Sources: packages/markdowndeck/README.md, packages/markdowndeck/src/markdowndeck/parser/content/content_parser.py