Skip to content

docs: bring the syntax reference up to 2.7.3, and surface it where people download - #558

Merged
PathGao merged 1 commit into
masterfrom
docs/syntax-doc-2.7.3-and-macos-note
Aug 8, 2026
Merged

docs: bring the syntax reference up to 2.7.3, and surface it where people download#558
PathGao merged 1 commit into
masterfrom
docs/syntax-doc-2.7.3-and-macos-note

Conversation

@PathGao

@PathGao PathGao commented Aug 8, 2026

Copy link
Copy Markdown
Collaborator

Three things, all documentation.

1. samples/markdown-syntax.md catches up with 2.7.3

Nothing in the release changed what renders, so the compatibility table is untouched — 25 PRs and not one of them adds or removes a spelling. What changed is behaviour, and five of those are demonstrable on the page itself:

Landed in 2.7.3 Where it goes
Edit jumps to the right-clicked fragment (#539) §17, first bullet — with ⌘E carrying the selection
Split-view sync by source line (#541) §17
Sticky scroll (#555) §17
The unpinned outline gets out of the way (#545) §17, folded into the existing outline bullet
CJK word-wise navigation, IME space no longer boxed (#546) §15, where the CJK samples already are

The outline line is written from what f29928a actually does — it collapses when you pick an entry, and when you reach past it to touch what it was covering — rather than from the shorter "steps aside" the commit subject suggests.

Checked and deliberately left alone: Copy Reference still writes in the document's own spelling (preferredReferenceStyle is unchanged), heading completion and task checkboxes were already described correctly. Encoding (#544), line endings (#540), the clipboard rewrite (#548, #551) and the load-race fixes (#552, #553) are not syntax and are not on this page.

Both language versions kept in step.

2. The document is findable now

It was one link in the nav and one clause inside a Features bullet. It now has its own section between Download and Installation from source, in both READMEs and in the generated release body.

  • The raw URL comes first. The primary action is downloading the file; reading it on GitHub is the fallback offered in parentheses. The document is built to be opened in Markpad — the preview shows each feature working and the editor beside it shows how each one is written, which is the whole point and the one thing GitHub cannot do.
  • It suggests handing the file to an AI. It is a complete list of what renders, so an assistant can reformat a document you already have or write a new one that uses the whole range, and you open the result in Markpad.
  • ## Markdown support is gone. In a README that word means the help desk. ## What Markpad renders says what the section is and does not collide with ## Features, which is already "what Markpad can do".

Release-body links are pinned to v${VERSION}, so each release points at the document as it shipped.

3. Both platform notices are generated, not pasted

The Windows SmartScreen notice has been added to the release body by hand every time — the workflow never produced it. It is in the generator now, unchanged word for word, so:

⚠️ It must no longer be pasted in by hand, or it will appear twice.

Beside it, a macOS Gatekeeper notice for what #209 costs a new user:

  • The unnotarized .dmg is refused on first launch, and the dialog offers only Cancel and Move to Trash — no way forward from that window.
  • Control-click → Open comes first, because it is one step. The System Settings → Privacy & Security → Open Anyway route is second, for people who already hit Cancel.
  • It names the consequence that gets reported as a separate bug: unsigned means macOS grants file access per prompt rather than remembering it, so the dialogs repeat — most visibly with auto-save on (turn it off in Settings; closing a tab still offers to save) and in documents with many local images, which can ask once per image.
  • Links to the self-signing workaround in #209, noting it has to be redone after each update.

Verification

build.yml parses, and the body-composition step was extracted and run locally against VERSION=2.7.3: the two notices, the table and the new section all render as intended, with no quoting damage from the echo lines. No code paths touched, so no test run is implied.

🤖 Generated with Claude Code

…ople download

**The syntax reference.** Nothing in 2.7.3 changed what renders, so the
compatibility table is untouched. What changed is behaviour, and five of
those are demonstrable on the page itself, so they belong in §17 and §15:
the right-click Edit jump (#539), split-view sync by source line (#541),
sticky scroll (#555), the unpinned outline getting out of the way (#545),
and CJK word-wise navigation with the IME space no longer boxed (#546).

The outline line is written from what f29928a actually does — it collapses
when you pick an entry or reach past it — rather than from the shorter
"steps aside" the commit subject suggests.

Checked and left alone: Copy Reference still follows the document's own
spelling (`preferredReferenceStyle`), heading completion and task
checkboxes were already described correctly. Encoding, line endings, the
clipboard and the load-race fixes are not syntax and are not on this page.

**Making it findable.** It was one link in the nav and one clause in a
Features bullet. It now has its own section between Download and
Installation from source, with the raw URL first so the primary action is
downloading the file rather than reading it on GitHub — the document is
built to be opened in Markpad, and reading it here is the fallback. The
section also suggests handing the file to an AI: it is a complete list of
what renders, so an assistant can reformat an existing document or write a
new one that uses the whole range.

"Markdown support" is gone as a heading. In a README that word means the
help desk; `## What Markpad renders` says what the section is, and does
not collide with `## Features`, which is where "what Markpad can do"
already lives.

The release body gets the same section, with the links pinned to the tag.

**The two platform notices.** The Windows SmartScreen note has been pasted
into the release body by hand since it was written — the workflow never
generated it. Both notices are generated now, so the macOS one cannot go
missing the release someone forgets, and the Windows one must no longer be
added by hand or it will appear twice.

The macOS notice covers what #209 costs a new user: an unnotarized `.dmg`
is refused on first launch with only Cancel and Move to Trash, so
Control-click → Open comes first as the one-step way past it and the
System Settings route second. It also names the consequence people report
as a separate bug — unsigned means file access is granted per prompt, so
the dialogs repeat, most visibly with auto-save on and in image-heavy
documents — and links to the self-signing workaround in #209, noting it
has to be redone after every update.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@PathGao
PathGao merged commit 1e6ddf1 into master Aug 8, 2026
4 checks passed
@PathGao
PathGao deleted the docs/syntax-doc-2.7.3-and-macos-note branch August 8, 2026 17:13
PathGao added a commit that referenced this pull request Aug 12, 2026
The app had two. Everything read `settings.osType`, which the Rust
`get_os_type` command fills in; TitleBar.svelte sniffed the user agent
for "Macintosh" and decided for itself. They disagree at exactly one
moment, and it is the moment the title bar is first painted:
`SettingsStore` sets `osType` from an `await invoke(…)` in its
constructor, so the field holds `'unknown'` for that round trip while
the user agent already knows. The title bar drew Mac chrome above tab
tooltips printing the Ctrl chords.

Repointing the title bar at `settings.osType` alone would have traded
that for a worse defect — a Mac rendering the Windows window controls
for those frames and then rearranging itself. So `utils/platform.ts`
holds one function that consults both in order: the os type once it is
resolved, the synchronous `navigator.platform` hint only before that.
The hint is the one Editor.svelte has used since #558 and it is frozen
at "MacIntel" on every Mac, so it cannot reach a different verdict than
the os type will — which is what makes consulting it first safe.

Also routes the four hand-written modifier ternaries #629 exported
`modifierFor` to delete: two in MarkdownViewer.svelte, TitleBar's, and
Settings.svelte's `? 'macos' : 'windows'` — which needed a platform
rather than a modifier, so it takes `platformOf` and picks up the fix
for the shortcut panel opening on the Ctrl chords on an unresolved Mac.

Two RULES rows keep both from coming back: `navigator.userAgent` and
`navigator.platform` outside utils/platform.ts, and the `=== 'macos' ?`
/ `'Cmd' : 'Ctrl'` decision outside the two helpers that own it.

Co-authored-by: PathGao <gaoyanbo@gaoyanbodeMacBook-Air.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
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