{"id":50438223,"url":"https://github.com/sokeikei/mdlook","last_synced_at":"2026-05-31T18:02:06.293Z","repository":{"id":360274126,"uuid":"1249284464","full_name":"SoKeiKei/MDLook","owner":"SoKeiKei","description":"A lightweight macOS Quick Look extension for Markdown files, with secure native Swift rendering and a companion app for setup and diagnostics.","archived":false,"fork":false,"pushed_at":"2026-05-25T17:47:25.000Z","size":1205,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T19:30:42.269Z","etag":null,"topics":["app-extension","finder","macos","markdown","quicklook","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SoKeiKei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-25T14:39:09.000Z","updated_at":"2026-05-25T17:47:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SoKeiKei/MDLook","commit_stats":null,"previous_names":["sokeikei/mdlook"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/SoKeiKei/MDLook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoKeiKei%2FMDLook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoKeiKei%2FMDLook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoKeiKei%2FMDLook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoKeiKei%2FMDLook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SoKeiKei","download_url":"https://codeload.github.com/SoKeiKei/MDLook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoKeiKei%2FMDLook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33742187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app-extension","finder","macos","markdown","quicklook","swift"],"created_at":"2026-05-31T18:02:03.955Z","updated_at":"2026-05-31T18:02:06.285Z","avatar_url":"https://github.com/SoKeiKei.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MDLook\n\n[English](#english) | 中文\n\n**MDLook** 是一个轻量的 macOS Markdown 快速预览扩展（Quick Look Extension）。在访达（Finder）中选中任意 `.md` 文件，按下**空格键**，即可立刻获得排版精美、安全可靠的阅读视图——无需打开任何编辑器，不占用任何后台资源。\n\n## 👀 界面预览\n\n| App | Preview |\n|---|---|\n| ![MDLook app window](Assets/README/app-window.png) | ![MDLook rendered preview](Assets/README/preview-rendered.png) |\n\n---\n\n## ✨ 为什么选择 MDLook\n\n| | MDLook |\n|---|---|\n| **体积** | 轻量，无任何第三方运行时依赖 |\n| **性能** | 纯 Swift 渲染，零 JavaScript 执行，瞬间出图 |\n| **安全** | 完全沙盒隔离，自动剔除 XSS 攻击向量 |\n| **隐私** | 不联网，所有渲染均在本机完成 |\n| **外观** | 自动适配 macOS 亮色 / 暗色模式 |\n| **免费** | MIT 开源，永久免费 |\n\n---\n\n## 💻 系统要求\n\n\u003e [!IMPORTANT]\n\u003e **仅支持搭载 Apple Silicon 芯片（M 系列）的 Mac。**\n\u003e 未对 Intel 芯片进行适配，亦未在低于 macOS 15 Sequoia 的系统上进行测试，不保证兼容性。\n\n- **芯片**：Apple Silicon（M1 及以上）\n- **系统**：macOS 15 Sequoia 或更高版本（推荐最新正式版）\n\n---\n\n## 🚀 快速安装\n\n1. 前往 [Releases](../../releases) 下载最新的 `MDLook.dmg`。\n2. 打开 DMG，将 `MDLook.app` 拖入「应用程序」文件夹。\n3. 双击打开 `MDLook.app`，完成扩展注册。\n\n\u003e [!NOTE]\n\u003e 当前发布包为开源测试分发版本，**未做 Apple Developer 签名或 notarization**。\n\u003e macOS 首次打开时可能提示来源未验证；如遇拦截，请在访达中对 `MDLook.app` 右键选择“打开”，或前往系统设置中手动放行。\n\n\u003e [!IMPORTANT]\n\u003e **必须手动开启扩展**：由于 macOS 安全策略限制，系统无法自动启用第三方 Quick Look 扩展。安装后请前往：\n\u003e\n\u003e **「系统设置 → 通用 → 登录项与扩展 → 快速查看」**，找到 **MDLookExtension** 并打开开关。\n\u003e\n\u003e 若未开启，访达中的空格键预览将无效，且 MDLook 应用内会显示红色提示引导您完成这一步骤。\n\n---\n\n## 📖 核心特性\n\n### 🎨 精致阅读排版\n- 正文与标题限制 `720px` 黄金阅读宽度，代码块与表格延伸至 `860px`，形成类 Notion / Medium 的错落层次感。\n- 字号 `16px`、行高 `1.75`、字距 `0.02em`，减少长文阅读疲劳。\n\n### 📊 阅读数据徽章\n- 文章顶部自动显示字数与预计阅读时间（SVG 矢量图标）。\n- 中英文混合统计：CJK 字符按字符数计，英文按单词数计，精准兼容中英混排。\n\n### ✏️ 高雅排版样式\n- `==高亮==`：纸质书荧光笔底边划线效果，亮 / 暗色模式自动切换。\n- `blockquote`：圆角淡色背景 + 左侧着色细边 + 斜体文字。\n- GFM Callouts：完整支持 `[!NOTE]` `[!TIP]` `[!IMPORTANT]` `[!WARNING]` `[!CAUTION]`。\n- 脚注：自动收集并渲染在文章底部。\n\n### 💻 静态代码高亮（零 JavaScript）\n- 纯 Swift 状态机分词，不加载任何外部脚本，沙盒内完全安全。\n- 支持：**Swift、JSON、YAML、Bash/Shell、JavaScript/TypeScript、Python、HTML/XML、CSS**。\n- LaTeX 公式（`$...$` 行内 / `$$...$$` 块级）：安全卡片预览。\n- Mermaid：展示高亮源码 + 安全提示（沙盒内不执行 JS 画图）。\n\n### 🔒 安全防护\n- 自动剔除所有 `\u003cscript\u003e` 标签与 XSS 攻击向量。\n- 默认拦截所有网络图片，防止 IP / 隐私泄露。\n- 拒绝 `file://` 外部图片协议。\n- 超过 2 MB 的文件自动降级为纯文本安全视图。\n\n---\n\n## 🗂️ 项目结构\n\n```\nMDLook/\n├── App/\n│   ├── MDLook/                        # 宿主 App（SwiftUI）\n│   │   ├── MDLookApp.swift            # App 入口\n│   │   ├── ContentView.swift          # 主界面：状态检测、警告卡片、操作按钮\n│   │   └── Assets.xcassets/           # 图标资源\n│   └── MDLookExtension/               # Quick Look 扩展\n│       └── MDLookPreviewProvider.swift # 扩展入口，调用渲染引擎\n├── Sources/\n│   ├── MarkdownPreviewCore/           # 核心渲染引擎（Swift Package）\n│   │   ├── MarkdownRenderer.swift     # Markdown → HTML 主渲染器\n│   │   ├── PreviewHTMLTemplate.swift  # HTML 模板与 CSS 样式表\n│   │   ├── ResourceResolver.swift     # 本地资源路径解析\n│   │   ├── HTMLEscaping.swift         # HTML 安全转义工具\n│   │   ├── PreviewErrorPage.swift     # 降级错误页面\n│   │   └── Models.swift               # 数据模型\n│   └── MDLookAppSupport/              # 宿主 App 共享库\n│       ├── AppCopy.swift              # 中英文 UI 文案\n│       ├── AppPreferences.swift       # 用户偏好（渲染开关等）\n│       └── QuickLookRefresher.swift   # Quick Look 刷新命令执行器\n├── Tests/\n│   ├── MarkdownPreviewCoreTestRunner/ # 核心渲染引擎单元测试\n│   └── MDLookAppLocalizationTestRunner/ # 共享文案与偏好/刷新逻辑测试\n├── Samples/\n│   ├── regression.md                  # 全特性回归测试文档 ★\n│   ├── images.md                      # 图片路径与安全拦截测试\n│   ├── large.md                       # 超大文件降级测试\n│   ├── real-world-readme.md           # 真实项目 README 渲染测试\n│   └── assets/                        # 测试用图片资源\n├── Assets/\n│   └── README/                        # README 展示截图\n├── Scripts/\n│   ├── install-dev.sh                 # 开发构建 \u0026 安装脚本\n│   ├── build-release.sh               # 打包 ZIP / DMG 发布脚本\n│   └── uninstall.sh                   # 完整卸载脚本\n├── Package.swift                      # Swift Package 定义\n├── project.yml                        # XcodeGen 工程配置\n└── README.md\n```\n\n---\n\n## 🛠️ 本地开发\n\n### 环境准备\n```sh\nbrew install xcodegen\nxcodegen generate\nopen MDLook.xcodeproj\n```\n\n### 编译 \u0026 安装（开发用）\n```sh\nScripts/install-dev.sh\n```\n仅编译并拷贝到 `/Applications/MDLook.app`，不自动操作扩展开关，方便手动测试。\n\n### 编译核心库 \u0026 运行测试\n```sh\nswift build\nswift run MarkdownPreviewCoreTestRunner\nswift run MDLookAppLocalizationTestRunner\n```\n\n### 刷新机制\n- “刷新 Quick Look” 按钮通过 `QuickLookRefresher` 串行执行 `qlmanage -r`、`qlmanage -r cache` 与 `killall Finder`，并把失败结果反馈回 UI。\n\n### 打包发布包（ZIP \u0026 DMG）\n```sh\nScripts/build-release.sh\n```\n产物输出至 `dist/MDLook.zip` 和 `dist/MDLook.dmg`。\n生成的 DMG 会排好拖拽安装布局，但默认仍是**未签名、未 notarize** 的开源测试包。\n\n### 完整卸载\n```sh\nScripts/uninstall.sh\n```\n注销扩展、清理偏好设置、删除应用包与本地 Debug 构建副本、刷新 Finder 缓存。\n\n---\n\n## 🔍 功能验证\n\n在访达中选中以下示例文件并按**空格键**：\n\n- [Samples/regression.md](Samples/regression.md)：**全特性回归测试文档**，涵盖 9 种代码高亮、数学公式、GFM Callouts、脚注、荧光笔标记、安全拦截等所有渲染特性。\n- [Samples/images.md](Samples/images.md)：验证含空格、中文路径的本地图片及网络图片安全拦截。\n\n---\n\n## 📄 开源许可\n\n本项目基于 **MIT 许可证** 开源，详见 [LICENSE](LICENSE)。\n\n---\n---\n\n\u003ca id=\"english\"\u003e\u003c/a\u003e\n\n# MDLook (English)\n\n[中文](#mdlook) | English\n\n**MDLook** is a lightweight macOS Quick Look Extension for Markdown files. Select any `.md` file in Finder and press **Space** — get a beautifully formatted, secure reading view instantly. No editor needed, zero background resource usage.\n\n## 👀 Screenshots\n\n| App | Preview |\n|---|---|\n| ![MDLook app window](Assets/README/app-window.png) | ![MDLook rendered preview](Assets/README/preview-rendered.png) |\n\n---\n\n## ✨ Why MDLook\n\n| | MDLook |\n|---|---|\n| **Size** | Lightweight — no third-party runtime dependencies |\n| **Performance** | Pure Swift rendering, zero JavaScript execution, instant preview |\n| **Security** | Full sandbox isolation, automatic XSS vector removal |\n| **Privacy** | Fully offline — all rendering happens on-device |\n| **Appearance** | Adapts automatically to Light and Dark mode |\n| **Price** | Free and open source (MIT) |\n\n---\n\n## 💻 System Requirements\n\n\u003e [!IMPORTANT]\n\u003e **Apple Silicon (M-series) Macs only.**\n\u003e Intel chips are not supported. Compatibility with macOS versions below macOS 15 Sequoia has not been tested and is not guaranteed.\n\n- **Chip**: Apple Silicon (M1 or later)\n- **OS**: macOS 15 Sequoia or later (latest release recommended)\n\n---\n\n## 🚀 Installation\n\n1. Download the latest `MDLook.dmg` from [Releases](../../releases).\n2. Open the DMG and drag `MDLook.app` into your Applications folder.\n3. Launch `MDLook.app` once to register the extension.\n\n\u003e [!NOTE]\n\u003e Current release artifacts are open-source test builds and are **not signed with an Apple Developer certificate or notarized**.\n\u003e On first launch, macOS may warn that the app cannot be verified. If that happens, right-click `MDLook.app` in Finder and choose \"Open\", or allow it manually in System Settings.\n\n\u003e [!IMPORTANT]\n\u003e **Manual activation required**: Due to macOS security policies, third-party Quick Look extensions cannot be auto-enabled. After installation, go to:\n\u003e\n\u003e **System Settings → General → Login Items \u0026 Extensions → Quick Look**\n\u003e\n\u003e and toggle on **MDLookExtension**. If not enabled, pressing Space in Finder won't show the preview. The MDLook app will display a red warning banner guiding you through this step.\n\n---\n\n## 📖 Features\n\n### 🎨 Refined Typography\n- Body text and headings constrained to a `720px` optimal reading width; code blocks and tables extend to `860px` — a Notion / Medium-style layered layout.\n- `16px` body size, `1.75` line height, `0.02em` letter spacing to reduce reading fatigue.\n\n### 📊 Reading Stats Badge\n- Word count and estimated reading time rendered at the top of each document with crisp SVG icons.\n- Accurate CJK + English mixed counting: CJK characters counted individually, English words counted by whitespace tokens.\n\n### ✏️ Elegant Visual Styles\n- `==highlight==`: Book-style highlighter underline effect with Light/Dark mode support.\n- `blockquote`: Soft rounded background, colored left border, italicized text.\n- GFM Callouts: Full support for `[!NOTE]` `[!TIP]` `[!IMPORTANT]` `[!WARNING]` `[!CAUTION]`.\n- Footnotes: Auto-collected and rendered at the bottom of the document.\n\n### 💻 Static Syntax Highlighting (Zero JavaScript)\n- Pure Swift state-machine lexer — no external scripts loaded, fully sandbox-safe.\n- Supported: **Swift, JSON, YAML, Bash/Shell, JavaScript/TypeScript, Python, HTML/XML, CSS**.\n- LaTeX (`$...$` inline / `$$...$$` block): Safe card-style preview.\n- Mermaid: Highlighted source preview with security notice (JS diagram execution disabled in sandbox).\n\n### 🔒 Security\n- All `\u003cscript\u003e` tags and XSS vectors are stripped automatically.\n- Remote images blocked by default to protect IP and privacy.\n- `file://` external image URLs are rejected.\n- Files exceeding 2 MB gracefully degrade to a safe plain-text view.\n\n---\n\n## 🗂️ Project Structure\n\n```\nMDLook/\n├── App/\n│   ├── MDLook/                        # Host app (SwiftUI)\n│   │   ├── MDLookApp.swift            # App entry point\n│   │   ├── ContentView.swift          # Main UI: status detection, warning card, actions\n│   │   └── Assets.xcassets/           # App icon assets\n│   └── MDLookExtension/               # Quick Look Extension target\n│       └── MDLookPreviewProvider.swift # Extension entry, calls rendering engine\n├── Sources/\n│   ├── MarkdownPreviewCore/           # Core rendering engine (Swift Package)\n│   │   ├── MarkdownRenderer.swift     # Markdown → HTML main renderer\n│   │   ├── PreviewHTMLTemplate.swift  # HTML template and CSS stylesheet\n│   │   ├── ResourceResolver.swift     # Local resource path resolution\n│   │   ├── HTMLEscaping.swift         # HTML safety escaping utilities\n│   │   ├── PreviewErrorPage.swift     # Graceful degradation error page\n│   │   └── Models.swift               # Data models\n│   └── MDLookAppSupport/              # Shared host-app library\n│       ├── AppCopy.swift              # Bilingual UI copy (zh/en)\n│       ├── AppPreferences.swift       # User preferences (rendering toggle etc.)\n│       └── QuickLookRefresher.swift   # Quick Look refresh command runner\n├── Tests/\n│   ├── MarkdownPreviewCoreTestRunner/ # Core renderer unit tests\n│   └── MDLookAppLocalizationTestRunner/ # Shared copy / preferences / refresh tests\n├── Samples/\n│   ├── regression.md                  # Full-feature regression test document ★\n│   ├── images.md                      # Image path and security blocking tests\n│   ├── large.md                       # Large file degradation test\n│   ├── real-world-readme.md           # Real-world README rendering test\n│   └── assets/                        # Sample image assets\n├── Scripts/\n│   ├── install-dev.sh                 # Dev build \u0026 install script\n│   ├── build-release.sh               # Package ZIP / DMG release script\n│   └── uninstall.sh                   # Full uninstallation script\n├── Package.swift                      # Swift Package manifest\n├── project.yml                        # XcodeGen project configuration\n└── README.md\n```\n\n---\n\n## 🛠️ Development\n\n### Setup\n```sh\nbrew install xcodegen\nxcodegen generate\nopen MDLook.xcodeproj\n```\n\n### Build \u0026 Install (Dev)\n```sh\nScripts/install-dev.sh\n```\nCompiles and copies to `/Applications/MDLook.app` only — does not auto-register the extension, keeping the test environment clean.\n\n### Build Core Library \u0026 Run Tests\n```sh\nswift build\nswift run MarkdownPreviewCoreTestRunner\nswift run MDLookAppLocalizationTestRunner\n```\n\n### Refresh Flow\n- The “Refresh Quick Look” action uses `QuickLookRefresher` to run `qlmanage -r`, `qlmanage -r cache`, and `killall Finder` in order, surfacing command failures back to the UI.\n\n### Package a Release (ZIP \u0026 DMG)\n```sh\nScripts/build-release.sh\n```\nOutputs `dist/MDLook.zip` and `dist/MDLook.dmg`.\nThe generated DMG includes a drag-to-install Finder layout, but it is still an **unsigned, non-notarized** open-source test package by default.\n\n### Uninstall\n```sh\nScripts/uninstall.sh\n```\nUnregisters the extension, clears preferences, removes app bundles plus local Debug build copies, and resets Finder/QL caches.\n\n---\n\n## 🔍 Manual Testing\n\nOpen these sample files in Finder and press **Space**:\n\n- [Samples/regression.md](Samples/regression.md): **Primary regression test document** — covers all rendering features: 9 syntax highlighting languages, math blocks, GFM callouts, footnotes, highlighter marks, and security blocking.\n- [Samples/images.md](Samples/images.md): Validates local paths with spaces/CJK characters and remote image blocking.\n\n---\n\n## 📄 License\n\nLicensed under the **MIT License**. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsokeikei%2Fmdlook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsokeikei%2Fmdlook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsokeikei%2Fmdlook/lists"}