Upgrading from MarkdownViewer

In v0.4.0 the app was renamed from MarkdownViewer to Sigla. The bundle identifier changed too, which scopes a fresh UserDefaults domain — so without a migration shim every existing user would lose every preference the app had ever written. Sigla migrates them automatically on first launch.

This page documents what changes, what’s preserved, and what to do if you hit a snag.

What changed

[!NOTE] The canonical cask is now slantedt/tap/sigla. The legacy cask name mdview from tvaisanen/tap is preserved via a tap_migrations.json entry, so brew install --cask mdview transparently resolves to slantedt/tap/sigla — no need to brew untap anything or re-install.

What gets migrated automatically

On the first launch of any v0.4.0+ build, Sigla copies your old UserDefaults from the pre-rename bundle ID into the new bundle ID’s domain. This happens before any UI reads defaults, so your settings appear preserved from the very first window.

Migrated:

• Document theme selection (DocumentTheme, DocumentDarkMode)
• Mermaid theme (MermaidTheme)
• Feature flags (FeatureFlag.Comments, FeatureFlag.Search, FeatureFlag.Renderer.<id>.Enabled, FeatureFlag.Extension.<id>.Enabled, FeatureFlag.Extensions.Enabled)
• Recent folders list
• Window frames
• Zoom level
• Per-file scroll positions
• Sidebar pin state
• Any custom Sigla-namespaced keys (Sigla.*)
• Any extension override acceptances

Not migrated (intentionally skipped):

• Apple/AppKit private namespaces (NS*, Apple*, com.apple.*, WebKit*) — stale window restoration blobs and system telemetry that shouldn’t follow the rename
• The migration sentinel itself

The shim is idempotent — it runs at most once and is sentinel-guarded. A Sigla.MigratedFromMarkdownViewerAt key gets set in the new domain with a Unix timestamp; subsequent launches see the sentinel and skip the migration entirely.

If you want to see what got migrated:

defaults read com.slantedt.sigla | head -50
defaults read com.slantedt.sigla Sigla.MigratedFromMarkdownViewerAt

What gets rebuilt (not migrated)

Render caches

Cached files under ~/Library/Caches/com.slantedt.markdownviewer/ are orphaned — the new bundle ID gets a fresh cache directory. The first PlantUML or Graphviz render after the upgrade runs uncached, then re-populates the new cache.

This is acceptable on purpose. The cache key shape changed in v0.4 (now namespaced by extension id so multiple binary-backed extensions coexist without collisions), so the old cache wouldn’t have been useful anyway.

If you want to reclaim the disk space:

rm -rf ~/Library/Caches/com.slantedt.markdownviewer

(Sigla doesn’t reap the old directory automatically — covered by a follow-up TODO.)

Bundled extension catalog

PlantUML is now a bundled extension, not a built-in renderer. If you had set the --plantuml-binary flag in the old CLI to point at a custom install, that flag no longer exists. Use the new override mechanism instead:

export SIGLA_BINARY_PLANTUML=/path/to/plantuml
mdv ./diagram.md

The variable is prepended to the manifest’s binary.search list, not a replacement — typos still fall through to the known good paths in the manifest.

CLI binary rename

The CLI was renamed from mdview to mdv. The brew cask installs both:

• mdv — canonical name, going forward
• sigla — forward-looking alias, identical behavior
• mdview — sunset alias, prints a deprecation notice, will be removed after a 12-month sunset window

All three are the same binary. Existing scripts that call mdview keep working; they just get a one-line warning to stderr nudging them toward mdv.

[!NOTE] Sample sunset notice (printed before normal output):

mdview: this name is deprecated; use `mdv` (or `sigla`). Will be removed in a future release.

The deprecation notice goes to stderr only — stdout is unaffected, so output-parsing scripts don’t break.

Upgrade checklist

1. Run brew upgrade --cask mdview (legacy install — auto-redirects to slantedt/tap/sigla) or brew upgrade --cask sigla (canonical name) — both upgrade the same install.
2. Launch Sigla. The first launch silently migrates your settings.
3. Verify the migration by checking that your theme, recent folders, and any enabled features are still as you left them.
4. If you have scripts calling mdview, plan a switch to mdv over the next 12 months.
5. If you used --plantuml-binary or environment overrides, switch to SIGLA_BINARY_PLANTUML.
6. (Optional) Reclaim cache disk space: rm -rf ~/Library/Caches/com.slantedt.markdownviewer.

If the migration didn’t take

If your settings appear reset after upgrading:

1. Check whether the sentinel was written:

   defaults read com.slantedt.sigla Sigla.MigratedFromMarkdownViewerAt

   • If you see a timestamp, the migration ran but the legacy domain was empty (clean install, or you wiped preferences).
   • If you get “does not exist”, the migration didn’t fire at all — file an issue with your About-version output.

2. Check whether the legacy domain still has data:

   defaults read com.slantedt.markdownviewer

   If this shows preferences but Sigla didn’t pick them up, force a re-migration by deleting the sentinel:

   defaults delete com.slantedt.sigla Sigla.MigratedFromMarkdownViewerAt

   Then relaunch. (Existing already-set keys in the Sigla domain win — the migration only fills gaps.)

Cross-references

• CLI reference — the new mdv surface in detail
• Extensions overview — where PlantUML lives now
• Getting started — fresh-install path if you’d rather start clean