Skip to content

Add markdown support for release notes#2810

Merged
zorgiepoo merged 39 commits into2.xfrom
push-rkpnprqmxruy
Dec 19, 2025
Merged

Add markdown support for release notes#2810
zorgiepoo merged 39 commits into2.xfrom
push-rkpnprqmxruy

Conversation

@zorgiepoo
Copy link
Copy Markdown
Member

@zorgiepoo zorgiepoo commented Dec 17, 2025

This adds markdown support to Sparkle's release notes. Similar to plain-text release notes, this allows using releasing notes in applications that aren't able to use WKWebView (e.g. Catalyst apps and apps without an outgoing network client entitlement which use the Downloader XPC Service). Other apps may also adopt markdown due to simplicity, although note it's not as expressive as HTML/CSS.

Other details:

  • Supports Markdown ordered/unordered lists, paragraphs, headers, code blocks, inline styling. Block quotes and thematic breaks are handled in simple manner through indentation and extra newline respectively. Tables are not supported. HTML isn't supported.
  • Requires macOS 12 or later due to leveraging Foundation / presentation intents for markdown processing. Older OS's and older Sparkle versions >= 2.4.0 will fall back to plain-text interpretation. Additionally, TextKit 2 is now adopted for macOS 12+, and TextKit 1 only code is to be avoided.
  • Adds delegate method to allow formatting / modifying the presented text before it will be shown for plain-text and markdown release notes. This, for example, can be used to adapting release notes based on currently installed version, but it could also open up styling release notes in other ways.
  • Adds sparkle:format="markdown" option to <description> element for embedded release notes (in addition to already existingsparkle:format="plain-text" option)
  • Adds support for generate_appcast to handle markdown release note files and embedded release notes.
  • Adds a MARKDOWN test mode to Sparkle Test App.

Decorative rendering for block quotes and thematic breaks was experimented through three ways (NSTextAttachmentCell, NSTextAttachmentViewProvider, NSTextViewportLayoutControllerDelegate). In the end I decided the complexity, risk, compatibility tradeoffs of these were not worthwhile enough, and I figure these are not critical to many change logs.

Screenshot 2025-12-16 at 8 43 48 PM

Fixes #2319

Misc Checklist

  • My change requires a documentation update on Sparkle's website repository
  • My change requires changes to generate_appcast, generate_keys, or sign_update

Testing

I tested and verified my change by using one or multiple of these methods:

  • Sparkle Test App
  • Unit Tests
  • My own app
  • Other (please specify)

Tested markdown support in Sparkle Test App, in other app using macOS Catalyst.

macOS version tested:
26.2 (25C56)
12.0 VM (at an earlier revision, I'll test this again at a later point).

Fix markdown detection for external release note links too.
Also make paragraph spacing proportional to font size.
We just need to render through entire vertical bounds and don't need to calculate number of lines.
@zorgiepoo zorgiepoo added this to the 2.9.0 milestone Dec 17, 2025
@zorgiepoo zorgiepoo merged commit 82d7da9 into 2.x Dec 19, 2025
2 checks passed
@zorgiepoo zorgiepoo deleted the push-rkpnprqmxruy branch December 19, 2025 23:10
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.

Add support for markdown release notes

1 participant