Skip to content

Comments#

Comments are private notes-to-self that live inside a note but stay out of your reader's view. They're written in standard HTML comment syntax, dim in the editor, and never appear in the preview, the export, or — by default — in any search outside the editor.

For writers, this is the equivalent of a pencil note in the margin of a manuscript: a reminder, a question to come back to, a half-formed idea, a fact to check. It travels with the work but never becomes the work.

Syntax#

Wrap any text in <!-- and -->. Comments can sit on a single line or span many.

Single Line#

The protagonist arrived at dusk. <!-- check sunset time for May 14 -->

The comment renders dimly in the editor next to the sentence and disappears in preview/export.

Multi-Line Block#

<!--
TODO before the next draft:
- raise the stakes in the second act
- decide whether the journal entries stay
- check the timeline against the Chapter 3 events
-->

The opening <!-- and closing --> must each appear at the start of a line for a multi-line block to be recognised. Everything in between is treated as comment content.

How Comments Appear in the Editor#

  • The whole region — markers and text — is dimmed to roughly 50% opacity so it visually recedes from your prose
  • Comment text uses its own font size (set in Settings → Editor → Comment Font Size) so you can shrink margin notes below body size if you want them less prominent
  • Spell-checking is suppressed inside comments by design — for the same reason they are dimmed, to keep margin notes from drawing visual attention away from the prose
  • The Task toolbar button is disabled while the cursor is inside a comment — a - [ ] line typed in a comment is not a real task and would never sync, so the button greys out to prevent confusion

Privacy by Design#

Comments are private by default. The setting that controls this is:

  • macOS: Settings → Privacy → Keep Comments Private (on by default)
  • iOS: Settings → Export & Maintenance → Privacy → Keep Comments Private (on by default)

While this is on:

  • Spotlight indexes the note without comment content. Searching for a phrase that only appears inside a comment will not surface the note from system search
  • The toolbar Search All Notes panel uses the same indexed text, so comments stay invisible there too
  • Preview, sharing, and every export format (HTML, PDF, DOCX, EPUB, RTF, TextBundle) already strip comments — that part doesn't depend on the toggle

Turn the toggle off and FoldNotes will re-index your collection so comments become findable from system search. The setting flips immediately and the index is rewritten in the background.

Why privacy is the default

The point of a margin note is that it's for you. Spotlight pulls from the system index — anything visible there shows up in widget previews, lock-screen suggestions, share extensions in other apps, and Continuity hand-offs. Privacy by default keeps half-formed thoughts and rough notes out of those surfaces unless you opt in.

Finding Text Inside Comments#

Even with privacy on, you can still search comments yourself from inside FoldNotes. Two routes:

In a single note#

Press Cmd+F (macOS) or open Find from the toolbar (iOS). Find runs against the full editor buffer, so it sees comment content. This is the right tool when you remember which note you stashed the note in.

Across the whole collection#

Open Search All Notes (Cmd+Shift+F on macOS, search icon on iPad), flip the * toggle to switch from text mode to search expression mode, and use the template below.

Template: Search Within Comments#

This expression matches text that appears anywhere inside an HTML comment — single line or multi-line block. Replace the placeholder with what you're looking for:

(?s)<!--.*?insert your search text here.*?-->

The (?s) at the front lets the search cross line breaks, so a multi-line comment block is treated as one searchable region. The .*? on either side of your text lets the expression match the rest of the comment without overrunning into the next one.

A few examples to copy and adapt:

What you want to find Search expression
Every comment that mentions "TODO" (?s)<!--.*?TODO.*?-->
Every comment that mentions a character name (?s)<!--.*?Vera.*?-->
Every comment that contains a ? (questions to self) (?s)<!--.*?\?.*?-->
Every comment, regardless of content (?s)<!--.*?-->

The last one — every comment — is a useful "where did I leave margin notes?" sweep before sending a draft out.

Once you have an expression that works, click the bookmark button next to the * toggle and choose Save Current Pattern…. Saved searches live in the collection (<collection>/.searches/) and sync across devices, so a "find all my margin notes" search you save on Mac is one tap away on iPad.

See Search for the full search expression reference.

When to Use a Comment vs. a Real Note#

Use a comment when… Use a separate note when…
The thought belongs to this passage The thought needs its own structure
It's a question, fact-check, or reminder It's research worth keeping permanently
You want it gone from the final output You want it backlinked and discoverable
It's likely to be resolved in the next pass It's reference material for the long term

Comments and notes complement each other: comments capture the friction of writing in place, notes capture knowledge you want to keep.

Limitations#

  • The search-expression mode used to sweep comments collection-wide is available on macOS and iPadOS but not on iPhone — typing expressions on a soft keyboard at phone size isn't a great experience, so the feature is held back there for now. iPhone still has full in-note Find (the second route above) and Spotlight, just not the * toggle in Search All Notes
  • Comment markers (<!-- and -->) must be balanced. An unclosed comment will dim everything from the opener to the end of the note until you close it
  • Nesting is not supported — HTML comments cannot contain other comments. If you need a comment inside a comment, write it as plain prose inside the existing block

Back to Writing →