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

[Kechos23]

Desktop Linked Workspace: original files, folder workflows and draft protection

This updates the reviewed Linked Workspace proposal with the requested hierarchy, actions and safety behavior. It depends on the separately proposed shared persistence/reliability changes; those are not presented as defects introduced by Linked Workspace.

User-facing behavior

• Group Vault, Linked Workspace and Secret Workspace under WORKSPACES. Use file-symlink / folder-symlink for real linked sources, keeping normal Vault icons unchanged.
• Provide Link file, Link folder and Create new linked file actions in the desktop toolbar and Linked Workspace menu. Keep creation separated from linking existing sources.
• Show source paths on hover instead of crowding file names. Use compact, distinct conflict/missing-source indicators with explanatory tooltips.
• Keep local recovery drafts separate from Vault storage, preserving linked-folder hierarchy. Saving the original is explicit; automatic persistence does not write the source.
• Support layout-independent Ctrl+S. Save As appends .md when needed and proposes the document name. A Vault export keeps its Vault document and focuses the new linked document; a linked Save As keeps both linked documents.
• Support linked file/folder conversion to independent Vault copies, including existing sidebar HTML dragging. Preserve folder hierarchy and original external files. Vault folder Save As creates a separate linked folder without merging into an existing destination.
• Keep conversions independent: reopening/rescanning the original can create a linked entry without consuming a Vault copy. Explicit rescan can restore entries previously excluded by removal/conversion.
• Use consistent status toasts and centered confirmations for consequential choices. Original-save confirmation has a preference to skip subsequent ordinary confirmations; conflict protection remains active.
• Keep the default Vault Welcome content unchanged. Identify unmodified built-in guides using metadata and use book-open-text for both guides. Update only the Linked Workspace guide.
• Allow middle-button tab closing in the shared web/desktop interface.

Safety and failure handling

• Capture live primary/split editor input before refresh, save, conversion and workspace maintenance, rather than relying on the debounce having finished.
• Preserve a local draft when a source changes, disappears or returns. Recheck relevant draft/source state after confirmation; cancelling does not discard the draft.
• Establish watchers for newly saved linked files. Persist bulk-removal exclusions before discarding records, and fail without a success message when persistence fails.
• Treat imported backup paths as data, not authorization to write external files or create watchers. Restored drafts need explicit relinking.
• Bound native file reads and folder scans; serialize relevant operations and report partial export/conversion results accurately.

Platform and limits

Linked-source actions require desktop native APIs and are hidden/disabled in the web app, including Docker-served deployments. Browser recovery content remains usable without reconnecting local paths. Native development/manual evidence is Windows-based; macOS/Linux native behavior is not claimed verified.

This branch uses the official Neutralino 6.5.0 runtime/client pins. Standard external HTML file drops remain Vault-copy imports. Native path drops, single-instance integration and the experimental pointer fallback are proposed separately in draft #269.

Scan limits: 10,000 Markdown files, 40,000 entries, 2,000 directories, depth 32, 20 MiB per Markdown source, 200 MiB staged content and a 60-second scan budget. Recovery is not a backup. Native APIs do not provide an atomic compare-and-write/no-overwrite guarantee, so a race with another process cannot be completely eliminated by application-side checks.

Validation

• 117 unit tests passed.
• Full Chromium run: 495/495 passed after the Media/Table focus-race fixes, before final locale completion. After completing the catalogs, 16 focused Chromium tests passed for localization/typography, desktop Save, action icons and web isolation; static validation also passed.
• Locale audit passed: 15 catalogs × 1,580 keys, with aligned placeholders and reviewed finite exceptions for legitimate unchanged terms. Actual English fallback labels were translated and internal toast IDs/search tokens/selectors were removed from extraction. Native-language quality still benefits from native-speaker review.
• The user accepted Windows smoke tests on the final official-runtime review executable: language switching/document preservation, Save/Save As, external conflict handling and folder conversion. Native macOS/Linux, Firefox/WebKit and comprehensive native failure/race testing remain unverified.

Review dependency

Depends on shared safety/reliability PR #279. Because this cross-fork PR still targets upstream main, its full diff currently includes that baseline. For the Linked Workspace-only changes, use the incremental comparison. After #279 merges, I will rebase onto the resulting upstream baseline.

[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-viewer	Ready	Preview	Oct 11, 2026 6:57pm UTC
markdown-viwer	Ready	Preview	Oct 11, 2026 6:57pm 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! ❤️

[Kechos23]

Thanks for the detailed review. I have separated the shared persistence fixes from this desktop feature and rebuilt the proposal on that baseline.

1. Linked Workspace menu: added linking existing files/folders and a clearly separated Create new linked file action. Desktop-only native actions do not appear in the browser build.
2. Guide icon: I used book-open-text for both built-in guides, identified through metadata rather than title alone. The Linked guide is an internal instructional document, not an externally linked source, so using a symlink icon there would imply a source-file relationship it does not have. Real linked sources use the requested symlink icons.
3. Physical hierarchy: linked recovery uses a separate storage root and retains the linked directory hierarchy. Conversion persists an independent Vault copy; originals are not deleted. Backup restore does not reactivate external-path authority.
4. Save confirmation: saving an original uses the application's centered confirmation styling with the ordinary-confirmation opt-out. Source conflicts still prevent an ordinary save from silently overwriting a changed original.

The four safety notes are also covered: live primary/split drafts are captured before refresh; returning missing sources do not overwrite dirty drafts; Save As links receive watchers; and bulk removal persists exclusions before removing records. Regression tests cover success, cancellation, changing state during confirmation, persistence failure and partial folder operations.

Additional related improvements include folder conversion/export, sidebar conversion using the existing HTML drag mechanism, less crowded source-path presentation, status-icon consistency and layout-independent saving. Remaining native atomicity limits are documented rather than represented as fully solved. If the desktop feature direction is not suitable for the project, I am happy to narrow or withdraw the feature proposal.

The shared safety baseline is now proposed separately in #279; the description links the incremental Linked Workspace diff for easier review.