ibz-04/gloamy/automating-keynote

Automating Keynote (JXA-first, AppleScript discovery)

Contents

• Relationship to the macOS automation skill
• Core framing
• Workflow (default)
• Quick Examples
• What to load

Relationship to the macOS automation skill

• This skill focuses on Keynote-specific automation (documents, slides, charts).
• Use automating-mac-apps for cross-app workflows or general macOS scripting foundations.
• Assumes Apple Events knowledge from the related skill.
• PyXA Installation: To use PyXA examples in this skill, see the installation instructions in automating-mac-apps skill (PyXA Installation section).

Core Framing

• JXA (JavaScript for Automation) enables macOS app scripting with JavaScript syntax.
• AppleScript dictionaries define Keynote's object model—discover via Script Editor.
• JXA objects are specifiers: read with methods like .name(), write with assignments.
• Production scripts use JXA for reliability; AppleScript for prototyping.
• Important: The JXA Path() function is required when specifying file paths to Keynote (e.g., for images, exports, or opening documents). Use Path("/path/to/file") instead of plain strings.

Workflow (default)

1) Discover terms in Script Editor > File > Open Dictionary > Keynote. 2) Prototype minimal AppleScript: tell application "Keynote" to get name of document 1. 3) Port to JXA: Application("Keynote").documents[0].name() with try-catch blocks. 4) Validate with read-only probes: Application("Keynote").documents.length > 0. 5) Use UI scripting only when dictionary lacks features (e.g. Application("System Events")).

Quick Examples

Prototype (AppleScript):

tell application "Keynote"
    get name of document 1
end tell

Production (JXA):

const keynote = Application("Keynote");
if (keynote.documents.length > 0) {
    console.log(keynote.documents[0].name());
}

Create Slide:

const doc = keynote.documents[0];
const slide = doc.slides.push(keynote.Slide({baseSlide: doc.masterSlides['Title - Center']}));
slide.defaultTitleItem.objectText = "New Slide";

Add Image to Slide (note Path() usage):

const slide = doc.slides[0];
const img = keynote.Image({
  file: Path("/Users/you/Desktop/diagram.png"),  // Path() required!
  position: { x: 100, y: 100 },
  width: 800
});
slide.images.push(img);

Validation Checklist

After implementing Keynote automation:

• [ ] Verify Keynote is running and accessible
• [ ] Test slide creation with master slide assignment
• [ ] Confirm image paths use Path() function
• [ ] Check text rendering in default text items
• [ ] Validate export operations complete without errors

When Not to Use

• For cross-platform presentation automation (use PowerPoint with Python libraries)
• When AppleScript alone suffices (skip JXA complexity)
• For web-based presentations (Google Slides, reveal.js)
• For non-macOS platforms

What to load

• Keynote JXA basics + runtime caveats: automating-keynote/references/keynote-basics.md
• Keynote recipes (slides, text, images, export): automating-keynote/references/keynote-recipes.md
• Deck generator example: automating-keynote/references/keynote-deck-generator.md
• Chart-aware deck pattern: automating-keynote/references/keynote-chart-aware-deck.md
• Advanced workflows (charts bridge, magic move, UI scripting): automating-keynote/references/keynote-advanced.md
• PyXA (Python) practical examples: automating-keynote/references/keynote-pyxa.md
• PyXA API Reference (complete class/method docs): automating-keynote/references/keynote-pyxa-api-reference.md