<p align="center"> <img src="https://github.com/k1LoW/deck/raw/main/img/logo.svg" width="200" alt="deck"> </p>

deck

deck is a tool for creating deck using Markdown and Google Slides.

Key concept

• Continuous deck building
  • Generate and modify deck iteratively.
• Separate content and design
  • Markdown for content, Google Slides for design.

Installation

Homebrew:

$ brew install deck

go install:

$ go install github.com/k1LoW/deck/cmd/deck@latest

Manual installation:

Download the binary from the releases page

Usage

Setup

Get and set your OAuth client credentials

• Create (or reuse) a developer project at https://console.cloud.google.com.
• Enable Google Slides API and Google Drive API at the API & Services page.
• Go to the Credentials page and click + CREATE CREDENTIALS at the top.
• Create an OAuth client ID type of credentials.
• Choose the type Desktop app.
  • Since there is no need to publish the app, add your email address as a test user from Google Auth Platform / Audience.
• Download the credentials file to ${XDG_DATA_HOME:-~/.local/share}/deck/credentials.json.

For CI/CD automation (Service Account)

If you're setting up deck for automated workflows (GitHub Actions, CI/CD pipelines), see Service Account Setup Guide.

Check your setup with deck doctor

You can verify if deck is ready to use and diagnose any configuration issues with the deck doctor command.

Prepare presentation ID and markdown file with deck new

deck requires two main components:

• Presentation ID: A unique identifier for your Google Slides presentation (e.g., xxxxxXXXXxxxxxXXXXxxxxxxxxxx from the URL https://docs.google.com/presentation/d/xxxxxXXXXxxxxxXXXXxxxxxxxxxx/edit)
• Markdown file: Your slide content written in markdown format

When creating a new presentation

You can create a new presentation with the deck new command:

$ deck new deck.md --title "Talk about deck"
Applied frontmatter to deck.md
xxxxxXXXXxxxxxXXXXxxxxxxxxxx

This will create (or update) the given markdown file with frontmatter containing the presentation ID and title.

Reusing theme from an existing presentation

To reuse the theme from an existing presentation, you have two options:

Option 1: Use the --base flag

$ deck new deck.md --base yyyyyyyYYYYyYYYYYYYyyyyyyyyy --title "Talk about deck"
xxxxxXXXXxxxxxXXXXxxxxxxxxxx

Option 2: Set a default base presentation in your configuration file

# ~/.config/deck/config.yml
basePresentationID: "yyyyyyyYYYYyYYYYYYYyyyyyyyyy"

With this configuration, you can reuse the theme from the base presentation without using the --base flag. If both the configuration and --base flag are present, the --base flag takes precedence.

When using an existing presentation

Get the presentation ID you want to work with. You can list all presentations with deck ls.

$ deck ls
xxxxxXXXXxxxxxXXXXxxxxxxxxxx    My Presentation
yyyyyYYYYyyyyyYYYYyyyyyyyyyy    Team Project Slides

[!NOTE] deck fully supports Google Shared Drives (Team Drives). Presentations stored in shared drives are automatically included in listings and can be operated on just like personal drive presentations.

To use this presentation, specify it with the --presentation-id flag or add it to your markdown file's frontmatter as presentationID.

Write your slides in markdown

Edit your markdown file with your favorite editor. Among horizontal rule syntaxes, three or more consecutive hyphens at the beginning of a line (e.g. ---) are treated as slide page separators. See Markdown file format for deck for details.

Apply markdown content to Google Slides with deck apply

$ deck apply deck.md

Watch mode

You can use the --watch flag to continuously monitor changes to your markdown file and automatically apply them to the presentation:

$ deck apply --watch deck.md

This is useful during the content creation process as it allows you to see your changes reflected in the presentation in real-time as you edit the markdown file.

[!NOTE] The --watch flag cannot be used together with the --page flag.

Open presentation in your browser with deck open

You can open your Google Slides presentation in your default web browser:

$ deck open deck.md

Markdown file format for deck

The Markdown used by deck consists of YAML frontmatter and a body section.

YAML Frontmatter

deck accepts YAML frontmatter at the beginning of your markdown file.

---
presentationID: xxxxxXXXXxxxxxXXXXxxxxxxxxxx
title: Talk about deck
---

# First Slide

Content...

The frontmatter must be:

• At the very beginning of the file
• Enclosed between --- delimiters
• Valid YAML syntax
• Use camelCase for fields used in deck settings

Available fields

• presentationID (string): Google Slides presentation ID. When specified, you can use the simplified command syntax.
• title (string): The title of the presentation. When specified, you can use the simplified command syntax.
• breaks (boolean): Control how line breaks are rendered. Default (false or omitted) renders line breaks as spaces. When true, line breaks in markdown are rendered as actual line breaks in slides. Can also be configured globally in config.yml.
• codeBlockToImageCommand (string): Command to convert code blocks to images. When specified, code blocks in the presentation will be converted to images using this command. Can also be configured globally in config.yml.
• defaults (array): Define conditional actions using CEL (Common Expression Language) expressions. Actions are automatically applied to pages based on page structure and content. Only applies to pages without explicit page configuration. Can also be configured globally in config.yml.

Supported Markdown syntax

deck supports CommonMark and selected GitHub Flavored Markdown extensions. For comprehensive documentation, see Markdown Support Documentation.

Key supported features:

• Bold ( **bold** )
• Italic ( *italic* __italic__ )
• Strikethrough ( ~~strikethrough~~ )
• List ( - * )
• Ordered list ( 1. 1) )
• Link ( [Link](https://example.com) )
• Angle bracket autolinks ( <https://example.com> )
• Code ( <code>`code`</code> )
• <br> (for newline)
• Image (![Image](path/to/image.png) )
• Block quote ( > block quote )
• Table (GitHub Flavored Markdown tables)
• RAW inline HTML (e.g., <mark>, <small>, <kbd>, <cite>, <q>, <span>, <u>, <s>, <del>, <ins>, <sub>, <sup>, <var>, <samp>, <data>, <dfn>, <time>, <abbr>)

Line break handling

deck provides configurable line break behavior through the breaks setting:

• Default (breaks: false): Single line breaks become spaces (per CommonMark/GFM specs)
• With breaks: true: Line breaks are preserved (GitHub-style rendering)
• For explicit breaks: Use hard line break syntax (two spaces at line end per CommonMark standard) or <br> tag

Example with breaks: true:

---
breaks: true
---
Text with
line breaks
preserved

Comments

HTML comments <!-- --> are used for speaker notes or page configuration.

How markdown maps to slide placeholders

deck inserts values according to the following rules regardless of the slide layout.

• The shallowest heading level within each slide content is treated as the title and inserted into the title placeholder ( CENTERED_TITLE or TITLE ) in order.
  • In most cases, this will be H1 (#), which is the standard for slide titles
• The next heading level (minimum level + 1) is treated as the subtitle and inserted into the subtitle placeholder ( SUBTITLE ) in order.
  • When H1 is used as the title, H2 (##) becomes the subtitle
• All other items are inserted into the body placeholder ( BODY ) in order.
  • The remaining contents are divided into one or more bodies by headings corresponding to the title or subtitle in the slide.

For example:

• Standard case: If a slide contains # (H1), then # becomes the title and ## becomes the subtitle
• Alternative case: If a slide only contains ## (H2) or deeper, then ## becomes the title and ### becomes the subtitle

[!NOTE] They are inserted in the order they appear in the markdown document, from the placeholder at the top of the slide (or from the placeholder on the left if placeholders are at the same height).

Also, if there are not enough placeholders, the remaining contents will not be rendered.

Example

Input markdown document:

# CAP theorem

## In Database theory

## Consistency

Every read receives the most recent write or an error.

## Availability

Every request received by a non-failing node in the system must result in a response.

## Partition tolerance

The system continues to operate desp