---

name: apple-notes-data-handling description: 'Handle Apple Notes data formats: HTML body, attachments, and rich content.

Trigger: "apple notes data handling".

' allowed-tools: Read, Write, Edit, Bash(osascript:*), Grep version: 1.6.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• macos
• apple-notes
• automation compatibility: Designed for Claude Code

---

Apple Notes Data Handling

Overview

Apple Notes stores note content as a restricted subset of HTML internally. The body() property in JXA returns this HTML, which includes <div>, <h1>-<h3>, <b>, <i>, <ul>, <li>, and Apple-specific classes for checklists and tables. Attachments (images, PDFs, sketches, scans) are embedded as <img> or object references but cannot be directly extracted via JXA — they require the attachments() property. Understanding these data formats is essential for building reliable import, export, and backup pipelines.

Prerequisites

• Written authorization for the accounts, folders, and note categories to be exported or transformed.
• An encrypted destination outside a shared directory, a retention limit, and a tested restore path.
• A conversion test corpus containing only synthetic notes; do not use the examples as proof that Apple Notes HTML is a stable public format.

Instructions

1. Scope reads to named folders and minimize collected fields before invoking osascript.
2. Write exports to a pre-created, owner-only directory and validate permissions before any data is emitted.
3. Treat HTML and attachment metadata as untrusted content: sanitize before rendering, and never execute embedded links or markup.
4. Hash or redact identifiers in operational logs; record only counts and completion state.

Note Body HTML Format

<!-- Apple Notes uses a subset of HTML wrapped in <div> blocks -->
<div><h1>Title</h1></div>
<div><br></div>
<div>Paragraph text here.</div>
<div><b>Bold text</b> and <i>italic text</i></div>
<div><br></div>
<div><ul><li>List item 1</li><li>List item 2</li></ul></div>

<!-- Checklists use Apple's custom class -->
<div><ul class="com-apple-note-checklist">
  <li class="done">Completed item</li>
  <li>Incomplete item</li>
</ul></div>

<!-- Tables (macOS Ventura+) use standard HTML tables -->
<div><table><tr><td>Cell 1</td><td>Cell 2</td></tr></table></div>

<!-- Tags (macOS Sonoma+) are stored as hashtags in body text -->
<div>#project #important</div>

Export All Notes to JSON

#!/bin/bash
# Full export with metadata — useful for backups and migration
osascript -l JavaScript -e '
  const Notes = Application("Notes");
  const results = Notes.defaultAccount.notes().map(n => ({
    id: n.id(),
    title: n.name(),
    body: n.body(),
    plaintext: n.plaintext(),
    folder: n.container().name(),
    created: n.creationDate().toISOString(),
    modified: n.modificationDate().toISOString(),
    attachmentCount: n.attachments().length,
  }));
  JSON.stringify(results, null, 2);
' > "$HOME/notes-export-$(date +%Y%m%d).json"

HTML to Markdown Converter

// src/data/html-to-markdown.ts
function notesHtmlToMarkdown(html: string): string {
  return html
    .replace(/<h1>(.*?)<\/h1>/g, "# $1")
    .replace(/<h2>(.*?)<\/h2>/g, "## $1")
    .replace(/<h3>(.*?)<\/h3>/g, "### $1")
    .replace(/<b>(.*?)<\/b>/g, "**$1**")
    .replace(/<strong>(.*?)<\/strong>/g, "**$1**")
    .replace(/<i>(.*?)<\/i>/g, "*$1*")
    .replace(/<em>(.*?)<\/em>/g, "*$1*")
    .replace(/<li class="done">(.*?)<\/li>/g, "- [x] $1")
    .replace(/<li>(.*?)<\/li>/g, "- [ ] $1")
    .replace(/<br\s*\/?>/g, "\n")
    .replace(/<div>/g, "").replace(/<\/div>/g, "\n")
    .replace(/<[^>]*>/g, "")
    .replace(/\n{3,}/g, "\n\n")
    .trim();
}

Attachment Handling

# List all notes with attachments and their counts
osascript -l JavaScript -e '
  const Notes = Application("Notes");
  Notes.defaultAccount.notes()
    .filter(n => n.attachments().length > 0)
    .map(n => n.name() + ": " + n.attachments().length + " attachments (" +
      n.attachments().map(a => a.name()).join(", ") + ")")
    .join("\n");
'

# Note: JXA cannot directly save attachment binary data.
# For full attachment export, use Shortcuts:
# shortcuts run "Export Note Attachments" --input-type text --input "Note Title"

Error Handling

Issue	Cause	Solution
body() returns empty string	Note contains only attachments (no text)	Check attachments().length; use plaintext() as fallback
HTML contains unexpected tags	Note created on iOS with unsupported formatting	Strip unknown tags; keep only known Apple Notes subset
plaintext() truncated	Very large note body	Export via body() HTML instead; convert after
Checklist state lost in export	Custom class not preserved in conversion	Map class="done" to [x] before stripping HTML
Attachment names are generic	Auto-generated names like Image.png	Use note title + index for meaningful filenames

Output

An export produces a scoped, encrypted artifact plus a separate receipt containing the folder scope, record count, checksum, and expiration—not note bodies, titles, or attachment names. A conversion produces Markdown only after the source has been sanitized and its unsupported constructs have been recorded for review.

Examples

For a migration rehearsal, export a synthetic test folder to an owner-only staging directory, convert it, validate the expected count and checksum, then securely remove the rehearsal artifact under the retention policy. For a live backup, use a job-owned encrypted volume and report only completed: 42 records to monitoring.

Resources

• Mac Automation Scripting Guide
• JXA Cookbook
• Apple Notes File Format (reverse-engineered)

Next Steps

For migrating between note platforms, see apple-notes-migration-deep-dive. For backup automation, see apple-notes-deploy-integration.