Automating Pages (JXA-first, AppleScript discovery)
Relationship to the macOS automation skill
- Standalone for Pages, aligned with
automating-mac-appspatterns. - Use
automating-mac-appsfor permissions, shell, and UI scripting guidance. - PyXA Installation: To use PyXA examples in this skill, see the installation instructions in
automating-mac-appsskill (PyXA Installation section).
Core framing
- Pages dictionary is AppleScript-first; discover there.
- JXA provides the logic and data handling.
- Objects are specifiers: References to Pages elements that require methods for reads (e.g.,
doc.body.text()) and assignments for writes (e.g.,doc.body.text = 'new text').
Example: Create Document
const pages = Application('Pages');
const doc = pages.Document({templateName: 'Blank'});
pages.documents.push(doc);
doc.body.text = "Hello World";Workflow (default)
- Discover: Open Script Editor > File > Open Dictionary > Pages.
- Prototype: Write minimal AppleScript to verify the command works.
- Port to JXA: Convert AppleScript syntax to JXA objects.
- Example: make new document becomes pages.documents.push(pages.Document()). - Add error handling (try/catch blocks).
- Optimize: Use batch text operations when possible to avoid performance penalties.
- Fallback: Use AppleScript bridge or UI scripting for dictionary gaps (e.g., specific layout changes).
Image Insertion (Critical Difference from Keynote)
IMPORTANT: Pages does NOT support direct image insertion like Keynote does:
// THIS WORKS IN KEYNOTE:
Keynote.Image({ file: Path("/path/to/image.png"), position: {x: 100, y: 100} });
// THIS DOES NOT WORK IN PAGES!
Pages.Image({ file: Path("/path/to/image.png") }); // ❌ Will failSolution: Use ObjC Pasteboard bridging (see pages-advanced.md for details):
ObjC.import('AppKit');
const nsImage = $.NSImage.alloc.initWithContentsOfFile("/path/to/image.png");
const pb = $.NSPasteboard.generalPasteboard;
pb.clearContents;
pb.setDataForType(nsImage.TIFFRepresentation, $.NSPasteboardTypeTIFF);
// Then use System Events to paste (Cmd+V)Example Script: See automating-pages/scripts/insert_images.js for a complete working example.
Common Pitfalls
- Image insertion: Pages lacks a native
Imageconstructor unlike Keynote. Use ObjC Pasteboard method. - Dictionary gaps: Some features (like sophisticated layout adjustments) aren't in the dictionary. Use the AppleScript bridge or UI scripting.
- Permissions: Ensure 'Accessibility' settings are enabled for UI scripting.
- Saving: Always use
doc.save({in: file_path})with a valid path object.
Validation Checklist
- Document opens without errors
- Text insertion and formatting succeeds
- Save operations complete with valid path objects
- Template application works if used
- Export to target format produces valid output (PDF, Word)
- Error handling covers missing files and permissions
When Not to Use
- Cross-platform document automation (use python-docx or pandoc)
- AppleScript alone suffices (skip JXA complexity)
- Web-based documents (Google Docs API)
- Non-macOS platforms
- Complex page layout requiring manual design tools
What to load
Level 1: Basics
- JXA Pages basics:
automating-pages/references/pages-basics.md(Core objects and document lifecycle)
Level 2: Recipes & Common Tasks
- Recipes (templates, export, text):
automating-pages/references/pages-recipes.md(Standard operations) - Export options matrix:
automating-pages/references/pages-export-matrix.md(PDF, Word, ePub formats) - Template strategy:
automating-pages/references/pages-template-strategy.md(Managing custom templates)
Level 3: Advanced
- Advanced patterns (tables, images, AppleScript bridge):
automating-pages/references/pages-advanced.md(Complex integrations) - UI scripting patterns:
automating-pages/references/pages-ui-scripting.md(Fallbacks) - Dictionary translation table:
automating-pages/references/pages-dictionary.md(AppleScript to JXA mapping) - PyXA (Python) alternative:
automating-pages/references/pages-pyxa.md
Example Scripts
- Image insertion:
automating-pages/scripts/insert_images.js(ObjC Pasteboard method for inserting images)