feat(link): add full Markdown link navigation support

- Main App: Enable links to external URLs, local files, and anchors
- QuickLook: Show non-intrusive toast for all links due to sandbox limitations
- JavaScript: Handle anchor clicks in JS, send other links to Swift via message handler
- Swift: Add linkClicked message handler and toast notification system
- Documentation: Update CHANGELOG and README with link navigation information

Author: xykong

CHANGELOG.md

@@ -1,7 +1,26 @@
 # Changelog
 
 ## [Unreleased]
-_无待发布的变更_
+
+### Added
+- **链接导航 (Link Navigation)**: 为 Markdown 文档添加完整的链接跳转支持。
+  - **主应用 (Main App)**:
+    - 外部 URL 链接 (http/https) 在默认浏览器中打开
+    - 相对路径链接 (`../file.md`, `./dir/file.md`) 正确解析并打开目标文件
+    - 页内锚点链接 (`#section`) 平滑滚动定位
+    - 支持所有文件类型 (`.md`, `.sql`, `.py`, `.json` 等)
+  - **QuickLook 预览 (Preview)**:
+    - 由于 macOS 沙盒限制,所有链接点击时显示优雅的 toast 提示而非打扰用户的对话框
+    - Toast 位置: 顶部居中
+    - 自动关闭: 3 秒后淡出消失
+    - 非阻塞: 用户可继续浏览文档
+    - 防重复: 同时只显示一个 toast
+    - 提示文案: "QuickLook 预览模式不支持链接跳转 / 请双击 .md 文件用主应用打开以使用完整功能"
+  - **技术实现**:
+    - 端到端桥接: JavaScript 通过 `window.webkit.messageHandlers.linkClicked` 将链接信息传递给 Swift
+    - 页内锚点: JavaScript 直接处理平滑滚动
+    - 文件路径解析: 支持相对路径、绝对路径、`file://` 协议等多种格式
+    - 日志增强: 所有链接点击操作记录到系统日志,便于调试
 
 ## [1.10.127] - 2026-02-10
 

README.md

@@ -14,6 +14,7 @@ A macOS QuickLook extension to beautifully preview Markdown files with full rend
 - **Syntax Highlighting**: Code blocks with language-specific highlighting
 - **Emoji**: Full emoji support with `:emoji_name:` syntax
 - **Table of Contents**: Auto-generated, collapsible navigation panel with smart highlighting
+- **Link Navigation**: Full link support in the main app. Click links to open external URLs, navigate to local files, or scroll to anchors. QuickLook shows a non-intrusive toast due to sandbox limitations.
 - **Theme**: Configurable appearance (Light, Dark, or System). Defaults to Light mode for better readability.
 - **Zoom**: Keyboard shortcuts (`Cmd +/-/0`), scroll wheel zoom (hold `Cmd` and scroll), and pinch gesture (two-finger pinch) with persistence
 - **Scroll Position Memory**: Automatically remembers scroll position for eachMarkdown file and restores it on next preview
@@ -197,6 +198,25 @@ Or simply select any `.md` file in Finder and press Space (QuickLook shortcut).
 **To grant permissions without dialog:**
 - You can pre-authorize in System Settings before using the app
 
+### Link Navigation in QuickLook
+
+**Problem:** Clicking links in QuickLook preview shows a toast notification instead of navigating.
+
+**Why this happens:**
+- macOS App Sandbox restricts QuickLook extensions from opening files or external URLs
+- This is a system-level security feature that cannot be bypassed
+- The toast is a non-intrusive way to inform users about this limitation
+
+**Solution:**
+- Double-click the `.md` file to open it in the main app instead
+- The main app has full link navigation support without sandbox restrictions
+
+**Supported link types (Main App only):**
+- External URLs: `https://example.com` → Opens in default browser
+- Relative paths: `./other.md` or `../dir/file.md` → Opens the target file
+- Anchors: `#section` → Smooth scroll to the section
+- All file types: `.md`, `.sql`, `.py`, `.json`, etc. → Opens with default app
+
 ## Acknowledgements
 
 This project is significantly inspired by and utilizes portions of [markdown-preview-enhanced](https://github.com/shd101wyy/markdown-preview-enhanced), created by Yiyi Wang (shd101wyy). We sincerely thank the author for their excellent work.

Sources/Markdown/Info.plist

@@ -10,6 +10,17 @@
 	<string>AppIcon</string>
 	<key>CFBundleIconName</key>
 	<string>AppIcon</string>
+	<key>CFBundleURLTypes</key>
+	<array>
+		<dict>
+			<key>CFBundleURLName</key>
+			<string>com.xykong.Markdown</string>
+			<key>CFBundleURLSchemes</key>
+			<array>
+				<string>markdownpreview</string>
+			</array>
+		</dict>
+	</array>
 	<key>CFBundleDocumentTypes</key>
 	<array>
 		<dict>

Sources/Markdown/MarkdownApp.swift

@@ -2,7 +2,6 @@ import SwiftUI
 import Sparkle
 
 class AppDelegate: NSObject, NSApplicationDelegate {
-    // Use SPUStandardUpdaterController for SwiftUI integration
     let updaterController = SPUStandardUpdaterController(
         startingUpdater: true,
         updaterDelegate: nil,
@@ -15,6 +14,37 @@ class AppDelegate: NSObject, NSApplicationDelegate {
         if CommandLine.arguments.contains("--register-only") {
             NSApplication.shared.terminate(nil)
         }
+        
+        NSAppleEventManager.shared().setEventHandler(
+            self,
+            andSelector: #selector(handleURLEvent(_:withReplyEvent:)),
+            forEventClass: AEEventClass(kInternetEventClass),
+            andEventID: AEEventID(kAEGetURL)
+        )
+    }
+    
+    @objc func handleURLEvent(_ event: NSAppleEventDescriptor, withReplyEvent replyEvent: NSAppleEventDescriptor) {
+        guard let urlString = event.paramDescriptor(forKeyword: AEKeyword(keyDirectObject))?.stringValue,
+              let url = URL(string: urlString) else {
+            print("❌ Invalid URL event")
+            return
+        }
+        
+        print("🔵 Received URL: \(urlString)")
+        
+        if url.scheme == "markdownpreview",
+           let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
+           let path = components.queryItems?.first(where: { $0.name == "path" })?.value {
+            let fileURL = URL(fileURLWithPath: path)
+            print("🔵 Opening file: \(fileURL.path)")
+            NSDocumentController.shared.openDocument(withContentsOf: fileURL, display: true) { _, _, error in
+                if let error = error {
+                    print("❌ Failed to open document: \(error.localizedDescription)")
+                } else {
+                    print("✅ Successfully opened document")
+                }
+            }
+        }
     }
 
     // MARK: - Helper Methods

Sources/Markdown/MarkdownWebView.swift

@@ -21,6 +21,7 @@ struct MarkdownWebView: NSViewRepresentable {
         webConfiguration.processPool = MarkdownWebView.sharedProcessPool
         let userContentController = WKUserContentController()
         userContentController.add(coordinator, name: "logger")
+        userContentController.add(coordinator, name: "linkClicked")
 
         let debugSource = """
         window.onerror = function(msg, url, line, col, error) {
@@ -89,6 +90,7 @@ struct MarkdownWebView: NSViewRepresentable {
         var isWebViewLoaded = false
         var pendingRender: (() -> Void)?
         weak var currentWebView: WKWebView?
+        var currentFileURL: URL?
 
         override init() {
             super.init()
@@ -218,12 +220,12 @@ struct MarkdownWebView: NSViewRepresentable {
         }
 
         func render(webView: WKWebView, content: String, fileURL: URL?) {
-            // Save the render action
+            currentFileURL = fileURL
+            
             pendingRender = { [weak self] in
                 self?.executeRender(webView: webView, content: content, fileURL: fileURL)
             }
 
-            // If already loaded, render immediately
             if isWebViewLoaded {
                 pendingRender?()
                 pendingRender = nil
@@ -308,7 +310,52 @@ struct MarkdownWebView: NSViewRepresentable {
                         pendingRender = nil
                     }
                 }
+            } else if message.name == "linkClicked", let href = message.body as? String {
+                os_log("🔵 Link clicked from JS: %{public}@", log: logger, type: .default, href)
+                handleLinkClick(href: href)
+            }
+        }
+        
+        private func handleLinkClick(href: String) {
+            if href.starts(with: "http://") || href.starts(with: "https://") {
+                if let url = URL(string: href) {
+                    os_log("🔵 Opening external URL: %{public}@", log: logger, type: .default, href)
+                    NSWorkspace.shared.open(url)
+                }
+                return
+            }
+            
+            guard let fileURL = currentFileURL else {
+                os_log("🔴 Cannot resolve relative path: no current file URL", log: logger, type: .error)
+                return
             }
+            
+            let baseDir = fileURL.deletingLastPathComponent()
+            var targetURL: URL
+            
+            if href.starts(with: "file://") {
+                guard let url = URL(string: href) else {
+                    os_log("🔴 Invalid file URL: %{public}@", log: logger, type: .error, href)
+                    return
+                }
+                targetURL = url
+            } else if href.starts(with: "/") {
+                targetURL = URL(fileURLWithPath: href)
+            } else {
+                targetURL = baseDir
+                for component in href.split(separator: "/") {
+                    let componentStr = String(component)
+                    if componentStr == ".." {
+                        targetURL.deleteLastPathComponent()
+                    } else if componentStr != "." {
+                        targetURL.appendPathComponent(componentStr)
+                    }
+                }
+            }
+            
+            os_log("🔵 Opening local file: %{public}@ (base: %{public}@, href: %{public}@)", 
+                   log: logger, type: .default, targetURL.path, baseDir.path, href)
+            NSWorkspace.shared.open(targetURL)
         }
 
         func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {

Sources/MarkdownPreview/PreviewViewController.swift

@@ -292,6 +292,7 @@ public class PreviewViewController: NSViewController, QLPreviewingController, WK
 
         let userContentController = WKUserContentController()
         userContentController.add(self, name: "logger")
+        userContentController.add(self, name: "linkClicked")
         webConfiguration.userContentController = userContentController
 
         os_log("🔵 initializing InteractiveWebView instance...", log: logger, type: .default)
@@ -446,6 +447,7 @@ public class PreviewViewController: NSViewController, QLPreviewingController, WK
         webView.stopLoading()
         webView.navigationDelegate = nil
         webView.configuration.userContentController.removeScriptMessageHandler(forName: "logger")
+        webView.configuration.userContentController.removeScriptMessageHandler(forName: "linkClicked")
 
         for recognizer in webView.gestureRecognizers {
             webView.removeGestureRecognizer(recognizer)
@@ -909,7 +911,12 @@ public class PreviewViewController: NSViewController, QLPreviewingController, WK
             return
         }
 
-        os_log("🔵 Link clicked: %{public}@", log: logger, type: .debug, url.absoluteString)
+        os_log("🔵 Link clicked: %{public}@", log: logger, type: .default, url.absoluteString)
+        os_log("🔵   - scheme: %{public}@, isFileURL: %{public}@, path: %{public}@", 
+               log: logger, type: .default, 
+               url.scheme ?? "nil", 
+               url.isFileURL ? "YES" : "NO", 
+               url.path)
 
         if let fragment = url.fragment, !fragment.isEmpty {
             var urlComponents = URLComponents(url: url, resolvingAgainstBaseURL: false)
@@ -923,31 +930,28 @@ public class PreviewViewController: NSViewController, QLPreviewingController, WK
             let isSameDocument = targetPath.isEmpty || currentPath == targetPath || url.scheme == nil
 
             if isSameDocument {
-                os_log("🔵 Scrolling to anchor: #%{public}@", log: logger, type: .debug, fragment)
-                let escapedFragment = fragment.replacingOccurrences(of: "'", with: "\\'")
-                let js = "document.getElementById('\(escapedFragment)')?.scrollIntoView({behavior:'smooth',block:'start'})"
-                webView.evaluateJavaScript(js, completionHandler: nil)
+                os_log("🔵 Same-document anchor link, letting JavaScript handle it", log: logger, type: .default)
                 decisionHandler(.cancel)
                 return
             }
         }
 
-        // Handle external links (http/https) - open in default browser
         if url.scheme == "http" || url.scheme == "https" {
-            os_log("🔵 Opening external URL in browser: %{public}@", log: logger, type: .debug, url.absoluteString)
+            os_log("🔵 Opening external URL in browser: %{public}@", log: logger, type: .default, url.absoluteString)
             NSWorkspace.shared.open(url)
             decisionHandler(.cancel)
             return
         }
 
-        // Handle local markdown file links - open with QuickLook or default app
-        if url.isFileURL && url.pathExtension.lowercased() == "md" {
-            os_log("🔵 Opening local markdown file: %{public}@", log: logger, type: .debug, url.path)
+        if url.isFileURL {
+            os_log("🔵 Opening local file with default app: %{public}@ (extension: %{public}@)", 
+                   log: logger, type: .default, url.path, url.pathExtension)
             NSWorkspace.shared.open(url)
             decisionHandler(.cancel)
             return
         }
 
+        os_log("🔵 Allowing navigation (unhandled scheme: %{public}@)", log: logger, type: .default, url.scheme ?? "nil")
         decisionHandler(.allow)
     }
 
@@ -965,13 +969,109 @@ public class PreviewViewController: NSViewController, QLPreviewingController, WK
                 os_log("🟢 Renderer Handshake Received!", log: logger, type: .default)
                 cancelHandshakeTimeout()
 
-                // Always mark as loaded and render. 
-                // We do NOT check !isWebViewLoaded here because a Reload action
-                // might have reset the WebView content (sending a new handshake)
-                // without the Swift side catching the navigation start event in time.
                 isWebViewLoaded = true
                 renderPendingMarkdown()
             }
+        } else if message.name == "linkClicked", let href = message.body as? String {
+            os_log("🔵 Link clicked from JS: %{public}@", log: logger, type: .default, href)
+            handleLinkClick(href: href)
+        }
+    }
+    
+    private func handleLinkClick(href: String) {
+        if href.starts(with: "http://") || href.starts(with: "https://") {
+            if let url = URL(string: href) {
+                os_log("🔵 Opening external URL: %{public}@", log: logger, type: .default, href)
+                let success = NSWorkspace.shared.open(url)
+                os_log("🔵 NSWorkspace.open result: %{public}@", log: logger, type: .default, success ? "SUCCESS" : "FAILED")
+                
+                if !success {
+                    os_log("🔴 Failed to open URL in QuickLook Extension sandbox", log: logger, type: .error)
+                    showLinkUnsupportedToast()
+                }
+            }
+            return
+        }
+        
+        os_log("🔵 Local file link clicked: %{public}@", log: logger, type: .default, href)
+        showLinkUnsupportedToast()
+    }
+    
+    private var toastView: NSView?
+    
+    private func showLinkUnsupportedToast() {
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            
+            if self.toastView != nil {
+                return
+            }
+            
+            let toastContainer = NSView()
+            toastContainer.wantsLayer = true
+            toastContainer.layer?.backgroundColor = NSColor.controlAccentColor.withAlphaComponent(0.95).cgColor
+            toastContainer.layer?.cornerRadius = 8
+            toastContainer.translatesAutoresizingMaskIntoConstraints = false
+            
+            let iconImageView = NSImageView()
+            iconImageView.image = NSImage(systemSymbolName: "info.circle.fill", accessibilityDescription: nil)
+            iconImageView.contentTintColor = .white
+            iconImageView.translatesAutoresizingMaskIntoConstraints = false
+            
+            let messageLabel = NSTextField(labelWithString: "QuickLook 预览模式不支持链接跳转")
+            messageLabel.textColor = .white
+            messageLabel.font = .systemFont(ofSize: 13, weight: .medium)
+            messageLabel.translatesAutoresizingMaskIntoConstraints = false
+            
+            let hintLabel = NSTextField(labelWithString: "请双击 .md 文件用主应用打开以使用完整功能")
+            hintLabel.textColor = NSColor.white.withAlphaComponent(0.9)
+            hintLabel.font = .systemFont(ofSize: 11)
+            hintLabel.translatesAutoresizingMaskIntoConstraints = false
+            
+            toastContainer.addSubview(iconImageView)
+            toastContainer.addSubview(messageLabel)
+            toastContainer.addSubview(hintLabel)
+            self.view.addSubview(toastContainer)
+            
+            NSLayoutConstraint.activate([
+                toastContainer.topAnchor.constraint(equalTo: self.view.topAnchor, constant: 16),
+                toastContainer.centerXAnchor.constraint(equalTo: self.view.centerXAnchor),
+                toastContainer.widthAnchor.constraint(lessThanOrEqualToConstant: 500),
+                
+                iconImageView.leadingAnchor.constraint(equalTo: toastContainer.leadingAnchor, constant: 12),
+                iconImageView.centerYAnchor.constraint(equalTo: toastContainer.centerYAnchor),
+                iconImageView.widthAnchor.constraint(equalToConstant: 20),
+                iconImageView.heightAnchor.constraint(equalToConstant: 20),
+                
+                messageLabel.leadingAnchor.constraint(equalTo: iconImageView.trailingAnchor, constant: 8),
+                messageLabel.trailingAnchor.constraint(equalTo: toastContainer.trailingAnchor, constant: -12),
+                messageLabel.topAnchor.constraint(equalTo: toastContainer.topAnchor, constant: 10),
+                
+                hintLabel.leadingAnchor.constraint(equalTo: messageLabel.leadingAnchor),
+                hintLabel.trailingAnchor.constraint(equalTo: messageLabel.trailingAnchor),
+                hintLabel.topAnchor.constraint(equalTo: messageLabel.bottomAnchor, constant: 2),
+                hintLabel.bottomAnchor.constraint(equalTo: toastContainer.bottomAnchor, constant: -10)
+            ])
+            
+            self.toastView = toastContainer
+            
+            toastContainer.alphaValue = 0
+            NSAnimationContext.runAnimationGroup({ context in
+                context.duration = 0.3
+                toastContainer.animator().alphaValue = 1
+            })
+            
+            DispatchQueue.main.asyncAfter(deadline: .now() + 3.0) { [weak self] in
+                guard let self = self, let toast = self.toastView else { return }
+                
+                NSAnimationContext.runAnimationGroup({ context in
+                    context.duration = 0.3
+                    toast.animator().alphaValue = 0
+                }, completionHandler: {
+                    toast.removeFromSuperview()
+                    self.toastView = nil
+                })
+            }
         }
     }
 

Tests/fixtures/example.json

@@ -0,0 +1,5 @@
+{
+  "name": "markdown-preview-test",
+  "version": "1.0.0",
+  "description": "Test file for link navigation"
+}