Skip to content

Add Finder Quick Actions for exporting Markdown - #255

Draft
mfauzaan wants to merge 3 commits into
mainfrom
codex/finder-export-quick-action
Draft

Add Finder Quick Actions for exporting Markdown#255
mfauzaan wants to merge 3 commits into
mainfrom
codex/finder-export-quick-action

Conversation

@mfauzaan

@mfauzaan mfauzaan commented Jul 30, 2026

Copy link
Copy Markdown
Member

Summary

Adds four Finder Quick Actions — Create PDF, Create PNG, Create HTML, and a combined Export Markdown — as Action extensions embedded in the app.

Right-click a Markdown file → Quick Actions → pick a format. Each one exports beside the source file the way Finder's own Convert Image does: no destination picker, Finder-style collision naming (full 2.pdf), and the main app never launches. The three format-specific actions still show the preview/font-size sheet, just with the format selector hidden.

The four targets share one source folder and one Info.plist, differing only by FINDER_ACTION_ICON_NAME and the format they're compiled for.

Icons

The icons are generated to match Apple's built-in Finder actions rather than approximated by hand — scripts/generate-action-icons.swift regenerates them and documents the spec, measured off Apple's own Create PDF as rendered in Login Items & Extensions:

Plate 26×26pt, corner radius 8, vertical gradient #B4B4B9#8E8E93
Glyph white, fitted to a centred 14pt box
Canvas 32×32pt — the list draws at natural size and won't upscale

Glyphs are Apple's real SF Symbol outlines (doc, photo, chevron.left.forwardslash.chevron.right, arrow.up.doc), read from NSSymbolImageRep's outlinePath rather than redrawn. doc is the same page-with-top-right-fold silhouette Finder uses for Create PDF, so that one is 1:1 and the others follow the same construction.

Two non-obvious findings, both commented in the generator so they aren't "fixed" later:

  • The list does not composite the grey plate. It draws icons exactly as authored — Apple's built-ins and third-party actions alike bake the plate into their own artwork. A bare glyph renders plate-less and undersized.
  • The plate is not a flat fill. Sampling a column down Apple's tiles gives ~#B4B4B9 at the top falling to systemGray #8E8E93 about 60% of the way down, then holding — a subtle top-lit sheen. Create PDF and Convert Image measure identically, so it's a system treatment, not per-icon artwork. A flat plate is visibly duller side by side.
  • Convert samples to sRGB before comparing against a screen capture. Raw bitmap components come back in the display's space, where #8E8E93 reads as #7B7B81.

PNG at 1x/2x rather than vector PDF: a fill in a CGPDFContext is written untagged and gets reinterpreted, whereas PNG carries an explicit sRGB profile.

Notes for review

Two undocumented Info.plist keys are load-bearing here, verified by removing each and observing the breakage (both now carry comments):

  • without NSExtensionServiceAllowsFinderPreviewItem the actions disappear from Finder's list entirely
  • without NSExtensionServiceFinderPreviewIconName the rows fall back to the containing app's icon

The changes to MarkdownWebView.swift / MarkdownHTML.swift are small #if EXPORT_ACTION_EXTENSION guards that compile the Mermaid popup and vendor warm-up out of the extension.

On a fresh install users must enable these once in System Settings → General → Login Items & Extensions → Actions. That's unavoidable for third-party Action extensions; Apple's built-ins are Finder-internal and exempt. Worth a first-launch prompt as a follow-up.

Test plan

  • Debug build succeeds with all four extensions embedded and validated, rebased on current main
  • All four actions appear in Finder's Quick Actions list
  • Real exports verified end-to-end (PDF, HTML), written beside the source; collision naming and cancel paths checked
  • Main app stays closed while an action runs
  • Icons verified live in Login Items & Extensions — plates measure #7B7B81, identical to all six Apple built-ins (Rotate Left, Markup, Create PDF, Trim, Convert Image, Remove Background)
  • Sanity-check exports on iCloud Drive and external volumes
  • Verify appearance in dark mode

🤖 Generated with Claude Code

mfauzaan and others added 3 commits July 30, 2026 09:22
Ship four Finder Quick Actions — Create PDF, Create PNG, Create HTML and a
combined Export Markdown — as Action extensions embedded in the app. Each
exports beside the source file the way Finder's own Convert Image does, with no
destination picker and Finder-style collision naming, and none of them launch
the main app.

The four targets share one source folder and Info.plist, differing only by
FINDER_ACTION_ICON_NAME and the format they are compiled for.

Icons are generated to match Apple's built-in Finder actions rather than
approximated by hand; see scripts/generate-action-icons.swift for the measured
spec and the two non-obvious findings behind it (the list draws icons as
authored and does not composite the grey plate, and it renders them 19/255
darker than authored).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The plate is not a flat fill. Sampling a column down Apple's tiles gives
~#B4B4B9 at the top falling to systemGray #8E8E93 about 60% of the way down and
staying there — a subtle top-lit sheen that a flat plate visibly lacks side by
side. Create PDF and Convert Image measure identically, so it is a system
treatment rather than per-icon artwork.

Their plate is also 26x26pt, not the 28 measured earlier; the extra 2pt made
ours read slightly heavy.

Also corrects a wrong note in the generator. The claim that the list composites
icons 19/255 darker was a measurement artifact: raw bitmap samples come back in
the display's space, where #8E8E93 reads as #7B7B81. Converting samples to sRGB
first shows the pipeline is transparent.

Verified live against the six built-in Finder actions: plate height and the
gradient now track Apple's within a few levels per row.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Reduce the padding around each glyph and draw them a step heavier — 16pt in the
26pt plate at .medium rather than 14pt at .regular. Apple's own glyphs read thin
and float at this size.

Create PNG now uses photo.on.rectangle.angled, the same glyph Finder's Convert
Image uses, whose width sits much closer to Apple's than plain photo. Create HTML
uses safari.

Drawing the glyphs switches from NSSymbolImageRep's `outlinePath` to the symbol
image itself. That property returns a simplified union for layered symbols — it
filled photo.on.rectangle.angled's front photo solid, losing the mountain and sun
— and it was only needed while these were vector PDFs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mfauzaan
mfauzaan marked this pull request as draft August 14, 2026 07:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant