Skip to content

Getting Started

Prerequisites

  • Python 3.12+
  • Google Cloud project with:
  • Google Slides API enabled
  • Google Docs API enabled (if using google_docs provider)
  • Google Sheets API enabled (if using google_sheets provider)
  • Google Drive API enabled
  • A service account with access to your target template deck/document/spreadsheet and Drive folders
  • For local PowerPoint output, a .pptx template and the optional slideflow-presentations[powerpoint] extra.

Install

Install from PyPI:

pip install slideflow-presentations

For editable local development:

git clone https://github.com/joe-broadhead/slideflow.git
cd slideflow
uv sync --extra dev --extra ai --extra docs --locked
source .venv/bin/activate

Configure Google credentials

SlideFlow accepts credentials via:

  1. provider.config.credentials in YAML for service-account JSON
  2. GOOGLE_DOCS_CREDENTIALS environment variable (for google_docs)
  3. GOOGLE_SHEETS_CREDENTIALS environment variable (for google_sheets)
  4. GOOGLE_SLIDEFLOW_CREDENTIALS environment variable (shared fallback)
  5. GOOGLE_APPLICATION_CREDENTIALS for ADC / Workload Identity Federation files
  6. Runtime Application Default Credentials

Environment credential values support either:

  • Path to service-account JSON file
  • Path to external-account / Workload Identity Federation JSON file
  • Raw JSON string content injected by a secret manager or GitHub Secrets

Keep external-account / Workload Identity Federation configs in trusted environment or ADC sources. provider.config.credentials accepts service-account JSON, but not external-account JSON from repository YAML.

Example:

export GOOGLE_SLIDEFLOW_CREDENTIALS=/absolute/path/service-account.json
export GOOGLE_DOCS_CREDENTIALS=/absolute/path/service-account.json
export GOOGLE_SHEETS_CREDENTIALS=/absolute/path/service-account.json
export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/external-account.json

For production service-account and Shared Drive setup, follow the end-to-end guide: Google Service Accounts & Shared Drives. Do not commit raw service-account JSON, OAuth client secrets, refresh tokens, or .env files. For keyless CI/CD, prefer a Google Workload Identity Federation auth step that sets GOOGLE_APPLICATION_CREDENTIALS or runtime ADC instead of storing a long-lived service-account key.

Create a template deck

Create a template and decide provider mode:

  • google_slides: Google Slides template deck with placeholder text and target slide IDs.
  • google_docs: Google Docs template with explicit section markers (for example {{SECTION:intro}}).
  • google_sheets: Google Sheets workbook output (workbook: schema with tab write rules).
  • powerpoint: local .pptx template with placeholders in text boxes or table cells.

You will need:

  • template_id (presentation/document ID from URL)
  • google_slides: slide IDs for each slide you modify
  • google_docs: marker ids that match presentation.slides[].id
  • google_sheets: either spreadsheet_id (reuse) or drive_folder_id (create destination)
  • powerpoint: template_path and either one-based slide indexes or native slide IDs.

Minimal config

provider:
  type: "google_slides"
  config:
    credentials: null # set GOOGLE_SLIDEFLOW_CREDENTIALS or use an untracked path
    template_id: "your_template_presentation_id"

presentation:
  name: "My First SlideFlow Deck"
  slides:
    - id: "your_slide_id"
      replacements:
        - type: "text"
          config:
            placeholder: "{{TITLE}}"
            replacement: "Hello SlideFlow"

Google Docs variant:

provider:
  type: "google_docs"
  config:
    template_id: "your_google_docs_template_id"

presentation:
  name: "My First SlideFlow Doc"
  slides:
    - id: "intro"
      replacements:
        - type: "text"
          config:
            placeholder: "{{TITLE}}"
            replacement: "Hello SlideFlow"

Google Sheets variant:

provider:
  type: "google_sheets"
  config:
    spreadsheet_id: "your_existing_spreadsheet_id" # or use drive_folder_id for create

workbook:
  title: "My First SlideFlow Workbook"
  tabs:
    - name: "kpi_current"
      mode: "replace"
      start_cell: "A1"
      include_header: true
      data_source:
        type: "csv"
        name: "kpi_source"
        file_path: "./data.csv"

Validate before build

slideflow validate config.yml
slideflow build config.yml
slideflow sheets validate workbook.yml
slideflow sheets build workbook.yml

Validation should be treated as mandatory in CI and release workflows.

For provider contract checks (recommended in CI):

slideflow validate config.yml --provider-contract-check

Provider contract checks use read-only Google scopes by default. Use --provider-contract-full-auth-fallback only for environments that explicitly accept validation with full build-provider scopes.

To discover built-in chart templates:

slideflow templates list --details
slideflow templates info bars/bar_basic

Run the checked-in smoke sample with no external credentials:

cd docs/quickstart/smoke
slideflow validate config.yml
slideflow build config.yml --params-path params.csv --dry-run

Next steps