From Markdown to Google Slides in Minutes: The Complete deck Handbook

“

“While my teammates spend an hour nudging text boxes, I sip coffee and watch my deck update itself.”
If that sounds appealing, deck might become your favorite command-line companion.

Table of Contents

1. What exactly is deck?
2. Three reasons to give it a spin
3. Install and authorize in five minutes
4. Creating or re-using a presentation
5. The three unbreakable Markdown → slide rules
6. Real-time preview with watch mode
7. Power-user tricks: auto-layout, code-to-image, CEL expressions
8. FAQ and quick troubleshooting
9. Wrap-up and next steps

1. What exactly is deck?

In one sentence: deck turns Google Slides into a plain-text workflow.
You write your story in Markdown, run a single command, and deck syncs it to a live Google Slides deck that you can share, present, or keep editing.
The next time you change a bullet, the slide updates automatically—no browser gymnastics required.

2. Three reasons to give it a spin

1. Continuous deck building
   Add, delete, or reorder slides by simply editing the Markdown file. Run deck apply and the Google Slides file reflects the changes instantly while preserving any hand-made graphics you added inside Slides.

2. Content and design stay separate
   Authors worry only about words and structure. Designers keep control of master slides, fonts, and color palettes. Everybody wins.

3. CLI-native and CI-ready
   A single line like deck apply slides.md can be dropped into GitHub Actions, GitLab CI, or any cron job. Teams wake up to a fresh deck every morning.

3. Install and authorize in five minutes

Prerequisites

• A Google account with Drive and Slides access
• A computer that can open console.cloud.google.com in a browser

Step 1: Install deck

Pick your preferred method:

After installation, run deck version to confirm the binary is on your path.

Step 2: Create OAuth credentials

1. Go to the Google Cloud Console.
2. Create or select a project.
3. APIs & Services > Enabled APIs & services → enable Google Slides API and Google Drive API.
4. Credentials > + Create Credentials > OAuth client ID.

   • Application type: Desktop app.
   • Name it anything, e.g. deck-cli.
5. Download the JSON file and rename it to credentials.json.

   • macOS/Linux: put it in ~/.local/share/deck/credentials.json.
   • Windows: %USERPROFILE%\.local\share\deck\credentials.json.

The first time you run deck ls, your browser will open an OAuth consent screen.
Grant permission once and a token.json file will be auto-generated next to credentials.json.
No more pop-ups after that.

“

For CI/CD: switch to a service-account key and share the target presentation with the service-account email.
See the included docs/setup-service-account.md for the exact steps.

4. Creating or re-using a presentation

Scenario A: start from scratch

deck new talk.md --title "AI-Powered Writing Workflows"

The command prints a long ID like 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms.
That ID is automatically inserted into talk.md as YAML front-matter:

---
presentationID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
title: AI-Powered Writing Workflows
---

Scenario B: reuse an existing template

deck new talk.md \
  --from 1wIik04tlp1U4SBHTLrSu20dPFlAGTbRHxnqdRFF9nPo \
  --title "AI-Powered Writing Workflows"

--from accepts any presentation ID.
The new file inherits the master theme, fonts, and color scheme.
You can also set a default template in your global config:

# ~/.config/deck/config.yml
basePresentationID: "1wIik04tlp1U4SBHTLrSu20dPFlAGTbRHxnqdRFF9nPo"

After that, running deck new talk.md without --from will still use the configured template.

Scenario C: work with an existing deck

1. List available presentations:

deck ls
1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms    My old talk
1wIik04tlp1U4SBHTLrSu20dPFlAGTbRHxnqdRFF9nPo    Team template

2. Copy the ID and either

   • add it to the YAML front-matter of your Markdown file, or
   • pass it on the command line: deck apply --presentation-id <ID> slides.md.

“

Shared drives: deck lists and edits presentations stored in Google Shared Drives exactly like personal ones.

5. The three unbreakable Markdown → slide rules

Rule 1: use --- to split pages

# Title slide

Subtitle here

---

## Agenda

- Background
- Solution
- Outlook

---

### Background

Body text ...

• Any line that starts with three or more hyphens and nothing else becomes a page break.
• The very first --- is ignored so the first slide doesn’t start empty.

Rule 2: the shallowest heading becomes the slide title

Example:

## CAP Theorem

### Consistency
All nodes see the same data at the same time.

### Availability
Every request receives a non-error response.

The slide title is “CAP Theorem”; the two ### headings become bullet groups in the body.

Rule 3: comments drive speaker notes or page config

<!-- {"layout":"section","freeze":true} -->

• JSON-formatted comments configure the slide (layout, freeze, ignore, skip).
• Plain-text comments become speaker notes.

6. Real-time preview with watch mode

Editing back-and-forth between an editor and a browser tab is painful.
deck solves this with --watch:

deck apply --watch talk.md

Save the file, wait one second, and the Google Slides tab refreshes automatically.
It feels like live reload for presentations.

“

--watch cannot be combined with the --page flag.

7. Power-user tricks

7.1 Auto-layout with YAML defaults

Add a block to your front-matter or global config:

defaults:
  # First slide always uses the title layout
  - if: page == 1
    layout: title
  # Slides with one H1 and one H2 get the section layout
  - if: titles.size() == 1 && headings[2].size() == 1
    layout: section-purple
  # Skip any slide with TODO in the speaker note
  - if: speakerNote.contains("TODO")
    skip: true
  # Fallback
  - if: true
    layout: title-and-body

Conditions use the CEL (Common Expression Language).
Available variables include page, pageTotal, titles, headings, codeBlocks, images, speakerNote, and more.
The first matching rule wins, so order matters.

7.2 Code blocks to crisp images

Install mermaid-cli:

npm i -g @mermaid-js/mermaid-cli

Then run:

deck apply -c 'mmdc -i - -o {{output}} --quiet' talk.md

Every triple-backtick block tagged mermaid is rendered to a transparent PNG and dropped into the slide, razor-sharp on any projector.

You can also:

• Use the built-in demo converter: -c 'go run testdata/txt2img/main.go'
• Chain different tools per language with a wrapper like laminate.

7.3 Multiple Google accounts or environments

deck apply slides.md --profile client-a
deck ls --profile personal

• Credentials file: credentials-client-a.json
• Token file: token-client-a.json

Profiles isolate OAuth flows completely, perfect for freelancers juggling client accounts.

8. FAQ and quick troubleshooting

9. Wrap-up and next steps

deck boils “making slides” down to two repeatable steps:

1. Write your story in Markdown.
2. Run deck apply.

If you already keep documentation in Git and edit Markdown daily, deck slots right in.

Ideas for going further:

• Add deck apply to your project’s Makefile: make slides
• Create a GitHub Action that runs deck apply --profile ci on every pull request and posts the share link as a comment.
• Store the base template ID in your org-wide config.yml so every new deck inherits brand colors automatically.

Happy writing—and even happier presenting.