feat(desktop): link Markdown files and folders alongside Vault copies

[Kechos23]

Summary

Add a desktop linked-source workflow alongside the existing Vault copies:

• Open Markdown files using their original filesystem paths and reuse an existing link when the same path is opened again.
• Keep recovery drafts separately from normal Vault documents. Editing saves a recovery draft; the original changes only through an explicit Save or Ctrl+S.
• Link Markdown folders, including nested folders, and detect external additions and changes without silently replacing a conflicting local draft.
• Group Workspace (Vault), Linked Workspace, and Secret Workspace under WORKSPACES, with distinct file/folder icons and source paths available on hover.
• Convert links into independent Vault copies without changing the originals, through the context menu or the existing internal HTML drag-and-drop mechanism.
• Offer Save and Save As for linked files. Save As creates a separate external file and link. Saving a Vault document externally preserves its Vault copy and focuses the linked destination.
• Provide an editable default Linked Workspace guide and preserve the normal Welcome document on first launch through a Markdown file association.

Removing a linked file or folder removes the application's reference, not the original files. Converted Vault copies remain independent even when their original source is reopened. Explicit folder rescans or re-adding a folder restore removed links; automatic background scans continue respecting removals.

Save dialogs propose the document title and add .md when no extension is specified. Ctrl+S also recognizes non-Latin keyboard layouts. Save As is context-menu-only; Ctrl+Shift+S keeps its existing scroll-sync behavior.

Review follow-up

All seven requested review points have been addressed. Related improvements cover nested expansion persistence, hover-only paths, consistent notification icons, migration recovery, safe conversion failures, and non-disruptive background refreshes while a context menu is open.

Platform scope and dependencies

Native linking, monitoring, and Save/Save As controls require desktop filesystem capabilities. Browser/Docker use retains its ordinary Workspace, existing HTML drag-and-drop, and Markdown download flow. Recovery documents containing desktop metadata remain usable as normal browser drafts without native controls; their metadata is preserved.

Desktop workflows were manually tested on Windows in the development prototype. macOS/Linux desktop behavior has not been manually verified. A separate review executable was built with the project's unchanged official Neutralino 6.5.0 runtime; it does not contain the custom runtime patches. Native manual testing of this exact review executable is still pending.

Validation

• 29 unit tests passed, including linked recovery storage, conversion, and interrupted migration recovery.
• 95 targeted Chromium tests passed, covering linked files/folders, storage, Save/Save As, notifications, background refreshes, the guide, internal HTML drops, web/desktop isolation, the merged slash menu, and existing editor/sidebar/tab behavior.
• Static build smoke check passed.
• Standard desktop resources were regenerated. The diff was checked to exclude custom release notes, versions, CI changes, runtime binaries, and custom runtime integration.
• Firefox/WebKit and macOS/Linux native manual testing were not run.

Demo

The existing demo predates the review polish. An updated recording can show the unified workspace layout, guide, independent conversion, and Save As workflow.

Possible desktop follow-ups

In a separate Windows prototype, native Explorer drops can offer Link original or Import to Workspace using real source paths across the full WebView. That currently requires a custom Neutralino build carrying the fix proposed in Neutralino PR #1845. I would propose the Markdown Viewer integration separately once the fix is available in an official stable runtime, with the linked-source model as its foundation.

Reusing the existing desktop window for files opened from the OS, without briefly showing a second window, is another separate prototype. It currently uses a Windows-specific native single-instance patch. I intend to explore an upstream runtime solution around Neutralino issue #901 before proposing its integration here. The single-instance patch is separate from the native drop fix.

Neither follow-up is required to review or use this PR. Their current implementations are Windows-only; equivalent behavior on other platforms would need separate investigation. If any desktop addition is outside the project's intended scope, please feel free to request a narrower change or decline it. I am happy to maintain the Windows-specific experiments separately.

[vercel]

@Kechos23 is attempting to deploy a commit to the BS Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
markdown-viwer	Ready	Preview	Oct 5, 2026 4:22pm UTC

[ThisIs-Developer]

Really a great idea, man. I tried and tested the linked files/folders workflow, and overall it works really well. This is a very useful feature for Markdown Viewer. 🙌

I have a few update requests that I think would make the feature more polished and consistent:

1. Linked file/folder icons
   Please use the Lucide icons file-symlink for linked files and folder-symlink for linked folders. This will make them visually different from normal Workspace files and folders.

2. Ctrl + S success notification
   After saving a linked file using Ctrl + S, the “Original file updated” toast appears without a proper success icon (Screenshot 1). Please make it consistent with the existing Import complete notification style shown in Screenshot 2, with a proper success/status icon.

   

3. Update the WORKSPACES structure
   Instead of having a separate Linked Locations section, I would prefer everything grouped under WORKSPACES in this order:

   • Workspace (Vault)
   • Linked Workspace
   • Secret Workspace

   Please refer to the AI-generated screenshot I shared as a UI reference.

   

4. Restore the Welcome document
   Inside Workspace (Vault), the default Welcome to Markdown document should still be available. Currently, it appears to be missing.

5. Linked Workspace guide file
   Please add a simple default guide/demo Markdown file inside Linked Workspace explaining how linked files and linked folders work. It can be very basic for now—I can improve the content later.

6. Separate linked recovery storage from the normal Vault storage
   Currently, recovery copies for linked files appear to be created inside the normal Workspace/Vault storage location.

   Please create a separate physical storage folder for Linked Workspace recovery files. Then:

   • Linked source recovery copies → stored under the Linked Workspace storage folder.
   • Normal Workspace files → remain under the normal Workspace/Vault folder.
   • When Convert to Workspace copy is used, the document should be moved/copied from the Linked Workspace recovery area into the normal Workspace folder.

   Screenshot 4 shows the current storage behavior for reference.

   

7. Linked file/folder context menu cleanup

   • For a linked file, rename “Remove link from Workspace” to “Remove linked file”.
   • For a linked folder, the current “Remove linked folder” label is already correct and can remain as it is.
   • Both Remove linked file and Remove linked folder should use the same red/danger text color as the remove/delete actions in the normal Workspace (Vault) context menu, so the UI stays consistent.
   • Copy source path: please check whether this action is really useful for the workflow. If it is not necessary, it can be removed. This part is optional.

These requests are a little detailed, so please take your time with them. The core feature itself is really good, and I appreciate the effort you’re putting into making Markdown Viewer better. 🚀

[ThisIs-Developer]

Thanks again for this contribution. I’ve already tested the feature and shared my detailed requested updates in this comment:
#262 (comment)
Please follow the points mentioned there before the final update. Take your time with the changes, as some of them involve the Workspace structure and linked-file storage behavior.

[Kechos23]

Thanks for testing the feature and for the detailed suggestions. I have addressed the seven review points:

1. Linked files/folders now use file-symlink / folder-symlink, including the linking commands. The Linked Workspace root keeps its existing link icon.
2. The Ctrl+S success notification uses the existing checkmark style. The other linked-workflow notifications were checked for consistent, rendered icons in both themes.
3. Everything is grouped under WORKSPACES in the requested order. Nested folder expansion works independently and persists. Inactive icons remain gray, and source paths are available on hover rather than taking space from filenames.
4. First launch through a Markdown file association now creates the normal Welcome document without stealing focus from the requested file. Intentional deletion in an existing workspace is respected.
5. Linked Workspace now has a simple editable default guide. It is created once and is not restored after intentional deletion.
6. Linked recovery drafts have their own physical storage folder. Migration includes recovery journals and validation. Conversion persists an independent normal Vault copy while leaving the original untouched; reopening the original does not absorb that copy.
7. Linked file removal uses the requested wording and normal danger styling. Folder removal keeps its existing wording and matching styling. Copy source path was removed; Open containing folder and hover paths remain.

Related improvements include explicit rescans restoring removed links, background refreshes preserving open context menus, Save/Save As with Markdown filenames and independent copies, and one-way linked-to-Vault conversion through the existing HTML drag-and-drop mechanism.

The update passed 29 unit tests, 95 targeted Chromium tests, and the static smoke check. A separate review executable was built using the project's unchanged official Neutralino runtime. Native manual validation is currently Windows-focused; macOS/Linux remain unverified. Browser/Docker controls are guarded and their ordinary workflows are covered by the regression tests.

The custom Windows native-drop and single-instance experiments remain separate. This PR does not need them. Please let me know if you would prefer any of the related additions split out or reduced in scope.

[ThisIs-Developer]

@Kechos23 Hi, thank you again for working through all of the previous points. I tested the latest version and I really like how the Linked Workspace feature is coming together. The previous requested updates look much better now.

I noticed a few smaller UI/workflow items, and I also checked a few edge cases against the current implementation.

1. Linked Workspace right-click menu

When I right-click Workspace (Vault), then a dropdown option shows with create new files/folders. I think the Linked Workspace should also have the same dropdown options.

It could contain:

• Link Markdown files
• Link Markdown folder

2. Welcome to Linked Workspace icon

The Welcome to Linked Workspace document currently uses the normal file icon. I understand that technically it is an internal document and not an external linked file, so the current implementation makes sense.

However, visually I think it would look more consistent if it used the Linked Workspace file/symlink icon as well, since the document belongs specifically to that workspace. Please share your opinion about this point with me.

3. Preserve linked-folder hierarchy inside Linked Workspace recovery storage

The Explorer UI correctly shows the linked folder hierarchy. For example, in my test the linked folder appears as its own folder and its files are nested underneath it.

However, when I inspect the file manager Markdown Viewer Vault, all linked recovery documents are stored directly under the Linked Workspace folder. The original linked-folder hierarchy is not represented there.

This would make recovery storage much easier to understand and inspect manually.

4. Confirmation before Save modifies the original linked file

I understand the current Linked Workspace design better now: edits are stored as recovery drafts, while Save / Ctrl+S explicitly updates the original external file. I think that behavior itself is reasonable.

My concern is accidental use. A user may open a linked document, edit it, press Ctrl+S out of habit, and not immediately realize that the original filesystem file will be changed.

Could we add a confirmation box (same UI as "reset-confirm-modal") the first time the user saves back to an original linked file?

Something like:

Save changes to the original linked file?
This will update the original file at:
C:\...\example.md

Cancel | Save to original

With a checkbox such as:

Don't show this warning again

Once the user understands the behavior, they can disable the confirmation permanently. I think this would make the feature safer without changing how Linked Workspace fundamentally works.

---

IMP NOTE

I personally haven’t reviewed the code deeply enough to confirm whether there are any potential data-loss or safety-related edge cases, so as an extra precaution, I asked Codex to review the implementation. It came back with the following four points:

Priority	Codex Finding	Location
P1	Check current editor text before refreshing linked files	script.js:11596–11601
P1	Preserve local drafts when a missing source returns	script.js:11613–11618
P2	Register watchers for links created by Save As	script.js:24997–25002
P2	Apply folder exclusions during bulk deletion	script.js:11809–11814

I’m not sure whether these are actual issues or just edge cases identified by Codex. If you could please check or reproduce these code paths and confirm that there is nothing to worry about, that would be completely fine as well.

I mainly wanted to raise them as a safety precaution before merging, especially for anything that could potentially affect users' files or local drafts.

If any of these points are valid, it would be really helpful if you could address them too.

Thanks a lot, man, for all the work you’ve done on this. I really appreciate it, and I really like the direction this feature has taken. I just want to make sure everything is safe and stable so we can get this merged as soon as possible. 👍

Love your work! ❤️