Sigla

Comments and highlights

Sigla supports inline comments anchored to spans of prose in your Markdown documents. Comments live in a hidden sidecar file next to the source — they travel with the file in git/Dropbox/etc., and the source itself is never mutated.

Comments are off by default and must be enabled in Settings.

Enable comments

  1. Open Settings: ⌘, (Sigla → Settings…).
  2. Go to the Comments tab.
  3. Toggle Enable Comments on.
  4. Restart Sigla.

[!NOTE] The comment menus, the side panel, and highlight injection wire up at launch. Toggling the feature mid-session requires a restart to take effect.

Once enabled, the Edit menu gains “Add Comment…” (⌘⇧M) and “Export Comments in a Prompt” (⌘⇧E). The View menu gains “Show Comments” (⌥⌘C).

Add a comment

  1. Select a span of prose in the rendered document.
  2. Press ⌘⇧M (or Edit → Add Comment…).
  3. A popover opens. Type your note. Press Save.

The selected span now renders with a soft yellow highlight, and a row appears in the Comments panel.

To edit or delete a comment, click its highlight in the document or its row in the Comments panel.

The Comments panel

⌥⌘C (View → Show Comments) toggles the right-side Comments panel. The panel lists comments in two sections:

  • Live — comments whose anchor span still exists in the current source.
  • Retired — comments whose anchor span was changed or removed by an external edit. The original text and your note are preserved; only the highlight is gone.

Click any row to scroll to its anchor in the document.

How comments persist

Each Markdown file with comments gets a hidden sidecar JSON file as a sibling:

~/notes/onboarding.md
~/notes/.onboarding.md.sigla.json    ← sidecar

The sidecar contains the schema version, an optional file checksum, the live comments list, and the retired comments list. Schema:

{
  "schemaVersion": 1,
  "fileChecksum": "…",
  "comments": [
    {
      "id": "01HXY…",
      "anchor": { "text": "the highlighted prose", "occurrence": 1 },
      "body": "your note here",
      "createdAt": "2026-05-23T14:30:00Z",
      "revisions": []
    }
  ],
  "retired": []
}
FieldPurpose
idULID — sortable timestamp + random suffix
anchor.textThe exact prose span the comment is attached to
anchor.occurrenceWhich occurrence (1-indexed) when the text appears multiple times in the document
bodyYour comment text
createdAtISO 8601 timestamp
revisionsArray of {at, body} — edits don’t overwrite, they append
retired[].reasonWhy the comment moved to retired (usually "anchor_not_found")

The sidecar file is hidden (leading .) so it doesn’t clutter Finder listings, but it’s plain JSON — checkable into git, diffable, hand-editable.

Anchor resilience

If you edit your Markdown externally:

  • Edits that don’t touch the highlighted span — the comment survives, highlight stays exactly where it was.
  • Edits that change or remove the highlighted span — the comment auto-retires. The original anchor text and your note are preserved in the retired array; you can read it but the in-document highlight is gone.

This is conservative on purpose. Sigla never guesses at a moved anchor — if the exact text doesn’t match, the comment retires.

Export comments as a prompt

⌘⇧E (Edit → Export Comments in a Prompt) copies a templated prompt to your clipboard, ready to paste into Claude or another LLM. The default template wraps each comment in XML for easy parsing:

<comment>
  <path>onboarding.md</path>
  <anchor line="42" startCol="0" endCol="38">the highlighted prose</anchor>
  <note>your comment text</note>
</comment>

Editing the template

Settings (⌘,) → Comments → “Comment export prompt” — a multi-line editor lets you customize the template. Below it, a reference grid lists every variable you can use.

Top-level variables

VariableMeaning
{{path}}Workspace-relative when inside an open folder; absolute otherwise
{{workspace_path}}Workspace-relative, empty when outside any workspace
{{absolute_path}}Always the absolute filesystem path

Inside {{#each comments}}…{{/each}}

VariableMeaning
{{index}}1-based comment number
{{line}}Anchor’s line in the source
{{startCol}}, {{endCol}}Anchor’s column range
{{text}}Anchor text — the highlighted prose
{{body}}Your comment note

Click “Reset to default” to restore the bundled XML template.

Privacy

[!NOTE] Comments never leave your filesystem. The sidecar JSON is written next to the source file you commented on; the export-to-prompt feature only copies to your local clipboard. Sigla makes no network calls related to comments.

If you don’t want a sidecar tracked in git, add it to .gitignore:

.*.sigla.json

Disabling comments

To turn comments off again:

  1. Settings (⌘,) → Comments → toggle off.
  2. Restart Sigla.

Existing sidecar files are not deleted — Sigla just stops reading or writing them until you turn the feature back on.

Cross-references