deck

build (https://github.com/k1LoW/deck/actions/workflows/ci.yml/badge.svg) !Coverage (https://raw.githubusercontent.com/k1LoW/octocovs/main/badges/k1LoW/deck/coverage.svg) !Code to Test Ratio (https://raw.githubusercontent.com/k1LoW/octocovs/main/badges/k1LoW/deck/ratio.svg) Ask DeepWiki (https://deepwiki.com/badge.svg)

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 (https://github.com/k1LoW/deck/releases)

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 (https://console.cloud.google.com/apis/library/slides.googleapis.com) and Google Drive API (https://console.cloud.google.com/apis/library/drive.googleapis.com) at the API & Services page (https://console.cloud.google.com/apis/dashboard).
• Go to the Credentials page (https://console.cloud.google.com/apis/credentials) and click + CREATE CREDENTIALS (https://console.cloud.google.com/auth/clients/create) 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 (https://console.cloud.google.com/auth/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 ( `` )
• Code ( `code` )
• `` (for newline)
• Image (!Image )
• Block quote ( > block quote )
• Table (GitHub Flavored Markdown tables)
• RAW inline HTML (e.g., , , , , , , , , , , , , , , , , , )

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 `` tag

Example with breaks: true:

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

Comments

HTML comments `` are used for speaker notes or page configuration.