Content Parsing & Extraction

Relevant source files

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

• packages/markdowndeck/src/markdowndeck/parser/content/content_parser.py
• packages/markdowndeck/src/markdowndeck/parser/slide_extractor.py
• packages/markdowndeck/src/markdowndeck/parser/directive/directive_parser.py
• packages/markdowndeck/src/markdowndeck/parser/section/section_parser.py
• packages/markdowndeck/src/markdowndeck/parser/section/content_splitter.py
• packages/markdowndeck/src/markdowndeck/parser/init.py

The Content Parsing & Extraction system is the foundational module of the MarkdownDeck library, responsible for transforming raw, enhanced Markdown text into a structured presentation model. This system manages the multi-stage conversion process, starting from the identification of individual slide boundaries to the recursive parsing of nested layouts and the fine-grained extraction of styling directives.

The architecture is designed to handle a specialized Markdown dialect that includes slide separators (===), vertical section dividers (---), and horizontal column dividers (***). It leverages the markdown-it-py library for standard Markdown tokenization while providing a custom abstraction layer to manage slide-specific elements like speaker notes, footers, and layout directives.

Sources: packages/markdowndeck/src/markdowndeck/parser/init.py, packages/markdowndeck/README.md:68-85

Architectural Overview

The parsing pipeline follows a sequential, four-component strategy to decompose a single Markdown document into a structured Deck object containing multiple Slide objects.

Slide Boundary Extraction

The SlideExtractor class is the entry point for the parsing pipeline. Its primary responsibility is to split a large Markdown document into discrete slide parts using the === separator.

Code Block Awareness

A critical feature of the extractor is its ability to ignore separators that appear within code blocks. It tracks state using fence patterns (```, ~~~, ````) to ensure that code examples containing === do not inadvertently trigger a slide split.

Content Decomposition

For each extracted slide, the component identifies and strips out special metadata elements:

• Speaker Notes: Captured via <!-- notes: ... --> blocks.
• Footers: Separated by the @@@ marker at the bottom of a slide.
• Slide-Level Directives: Leading bracketed blocks (e.g., [background=#000]) at the very start of slide content.

Sources: packages/markdowndeck/src/markdowndeck/parser/slide_extractor.py:16-118

Sectional Layout Hierarchy

After slides are isolated, the SectionParser and ContentSplitter process the internal layout of each slide. This stage establishes a hierarchy of "Vertical" and "Horizontal" containers.

Section Types

Marker	Section Type	Description
===	Slide	The primary container for a single presentation page.
---	Vertical	Splits a slide into stacked sections (rows).
***	Horizontal	Splits a vertical section into side-by-side columns (rows of sections).

Sources: packages/markdowndeck/src/markdowndeck/parser/section/section_parser.py:64-124, packages/google-workspace-mcp/src/google_workspace_mcp/resources/slides.py:38-70

Recursive Section Processing

The SectionParser constructs a root_section for every slide. It first splits content by --- into vertical parts, then further splits those parts by *** if columns are detected. This results in a tree of Section models where the type property is either "section" or "row".

Content Element Tokenization

The ContentParser performs the final conversion of text into renderable elements (Titles, Lists, Tables, etc.). It utilizes a list of specialized formatters to process MarkdownIt tokens.

Element Formatters

The system dispatches tokens to specific formatters based on the token type:

• ListFormatter: Handles unordered and ordered lists, preserving nesting levels.
• TableFormatter: Extracts headers and rows for slide-native table objects.
• TextFormatter: Manages paragraphs, headers (H1-H6), and inline formatting like bold or italic.
• CodeFormatter: Processes code blocks with language-specific identifiers.

Sources: packages/markdowndeck/src/markdowndeck/parser/content/content_parser.py:35-48, 169-195

Directive Scoping Logic

Directives (e.g., [width=50%]) are handled with a specific inheritance and scoping model:

1. Slide-Level: Applied to the entire slide background or global theme.
2. Section-Level: Leading directives in a section apply to all elements within that container.
3. Element-Level: Directives immediately preceding an element (or on the same line for titles) apply only to that specific element.

Sources: packages/markdowndeck/src/markdowndeck/parser/content/content_parser.py:118-144, tests/markdowndeck/unit/parser/test_parser_diagnostics.py:199-235

Directive Parsing & Conversion

The DirectiveParser uses regular expressions to identify and extract key-value pairs enclosed in square brackets.

Type Conversion

Extracted string values are converted into functional data types using a suite of converters:

• Dimension: Converts fractions (1/2), percentages (50%), or pixels into numeric points.
• Alignment: Maps strings like left or center to AlignmentType enums.
• Style: Parses complex strings for colors (hex or theme names) and image URLs.

Sources: packages/markdowndeck/src/markdowndeck/parser/directive/directive_parser.py:23-62

Directive Registration

# Core Directive Types Managed by DirectiveParser
self.directive_types = {
    "width": "dimension",
    "height": "dimension",
    "align": "alignment",
    "valign": "alignment",
    "background": "style",
    "padding": "dimension",
    "color": "style",
    "fontsize": "dimension",
    "line-spacing": "float",
    "cell-align": "alignment"
}

Sources: packages/markdowndeck/src/markdowndeck/parser/directive/directive_parser.py:34-60

Conclusion

The Content Parsing & Extraction system provides a robust, state-aware pipeline for transforming hierarchical Markdown into a presentation-ready format. By decoupling slide extraction, sectional layout organization, and element-level formatting, the system maintains high technical accuracy while supporting complex features like nested columns and scoped styling directives.