MarkdownDeck Overview & CLI
Relevant source files
The following files were used as context for generating this wiki page:
MarkdownDeck is an enterprise-grade Python library designed to transform an enhanced Markdown dialect into professional Google Slides presentations. It acts as a robust abstraction layer over the Google Slides API, handling complex layout calculations, coordinate systems, and content overflow management that are typically difficult for developers and LLMs to manage directly.
Sources: packages/markdowndeck/README.md:12-16
Within the arclio-mcp-tooling monorepo, MarkdownDeck serves as a foundational engine. It is utilized by the google-workspace-mcp package to provide the create_presentation_from_markdown tool, enabling AI assistants to generate slides through the Model Context Protocol.
Sources: packages/markdowndeck/README.md:125-128, packages/google-workspace-mcp/README.md:167-170
Core Architecture
MarkdownDeck utilizes a decoupled four-stage pipeline to process Markdown into a final presentation. This architecture ensures that layout logic is separated from content distribution and API generation.
The diagram shows the sequential flow of data from raw Markdown to the final Google Slides API requests.
Sources: packages/markdowndeck/README.md:88-105
Pipeline Stages
| Stage | Component | Description |
|---|---|---|
| Parse | Parser | Converts Markdown text into a structured Deck object, identifying slides and directives. |
| Layout | LayoutCalculator | Performs spatial planning to calculate the ideal position and size for every element based on layout rules. |
| Overflow | OverflowHandler | A recursive engine that partitions content across multiple slides if it exceeds slide boundaries. |
| Generate | ApiRequestGenerator | Consumes finalized slide objects to produce validated JSON payloads for the Google Slides API. |
Sources: packages/markdowndeck/README.md:92-105, packages/markdowndeck/src/markdowndeck/init.py:22-44
Command Line Interface (CLI)
The CLI provides a direct interface for users to create presentations from Markdown files or standard input. It handles authentication via several methods and communicates with the core library to execute the generation pipeline.
Sources: packages/markdowndeck/src/markdowndeck/cli.py:15-20
Authentication Flow
The CLI supports three primary authentication methods, prioritized in the following order:
- Service Account: Uses the path provided in
GOOGLE_APPLICATION_CREDENTIALS. - Environment Variables: Uses
SLIDES_CLIENT_ID,SLIDES_CLIENT_SECRET, andSLIDES_REFRESH_TOKEN. - Local Token/OAuth: Uses
token.jsonor triggers an interactive browser flow usingcredentials.json.
The sequence illustrates how the CLI resolves credentials before calling the library's creation function.
Sources: packages/markdowndeck/src/markdowndeck/cli.py:32-84
CLI Commands and Arguments
The main entry point for the CLI is markdowndeck create.
| Argument | Flag | Description | Default |
|---|---|---|---|
input | N/A | Path to the Markdown file or - for stdin. | Required |
--title | -t | Title of the created presentation. | "Markdown Presentation" |
--output | -o | Path to save the resulting JSON (Presentation ID/URL). | Optional |
--verbose | -v | Enables DEBUG level logging. | False |
Sources: packages/markdowndeck/src/markdowndeck/cli.py:118-142
Layout & Spatial Constants
The library follows a "Blank Canvas First" principle, using a standard 16:9 aspect ratio for slides. Default dimensions are based on a 72 DPI scale.
Sources: packages/markdowndeck/src/markdowndeck/layout/constants.py:155-159, packages/markdowndeck/src/markdowndeck/cli.py:129-130
Slide Dimensions & Zones
| Constant | Value | Description |
|---|---|---|
DEFAULT_SLIDE_WIDTH | 720.0 | 10 inches at 72 DPI. |
DEFAULT_SLIDE_HEIGHT | 405.0 | 5.625 inches (16:9 ratio). |
HEADER_HEIGHT | 90.0 | Reserved space for titles/subtitles. |
FOOTER_HEIGHT | 30.0 | Reserved space for footer content. |
Sources: packages/markdowndeck/src/markdowndeck/layout/constants.py:10-12, packages/markdowndeck/src/markdowndeck/layout/constants.py:155-159
Typography Defaults
MarkdownDeck applies specific font sizes and line heights to different Markdown levels to ensure readability in a slide format.
- H1 (Title): 24.0 pt (Line Height: 1.2)
- H2 (Subtitle): 20.0 pt (Line Height: 1.2)
- Paragraph (Body): 14.0 pt (Line Height: 1.4)
- Code Block: 12.0 pt (Line Height: 1.2)
Sources: packages/markdowndeck/src/markdowndeck/layout/constants.py:27-42
Integration with Library Entry Points
The library exposes two main programmatic entry points in the top-level __init__.py:
create_presentation(): A high-level function that parses Markdown, calculates layout, handles overflow, and executes the Google Slides API requests.markdown_to_requests(): A "dry-run" function that returns the raw API request batches without executing them, useful for custom integration or auditing.
def create_presentation(
markdown: str,
title: str = "Markdown Presentation",
credentials: Credentials | None = None,
service: Resource | None = None,
) -> dict:
# 1. Parse and Layout
deck = _process_markdown_to_deck(markdown, title)
# 2. API Execution
api_client = ApiClient(credentials, service)
return api_client.create_presentation_from_deck(deck)
Sources: packages/markdowndeck/src/markdowndeck/init.py:53-70, packages/markdowndeck/src/markdowndeck/init.py:73-89
Conclusion
The MarkdownDeck system provides a comprehensive bridge between declarative content (Markdown) and the imperative Google Slides API. Through its multi-stage pipeline and versatile CLI, it ensures that complex presentation elements—such as multi-column layouts and overflow text—are handled predictably while maintaining enterprise-grade authentication standards.
Sources: packages/markdowndeck/README.md:12-25, packages/markdowndeck/src/markdowndeck/cli.py:32-35