Ledge.sh 可运行的 Markdown 笔记本 – 特性、使用场景与社区反馈

Ledge.sh 允许你在 Markdown 笔记中直接运行代码，将纯文本文档转变为交互式笔记本

Ledge.sh 是一个免费的、采用 Apache‑2.0 许可证的笔记本，可在 fenced code blocks 中执行 shell 命令、Python、SQL 和 AI 提示。在代码块上按下 ⌘↩，其输出将流式显示在该块下方，使笔记兼具文档与实时执行环境的功能。

每个笔记的持久化 shell

每个笔记拥有自己的 shell 会话，因此 cd、导出的变量或激活的虚拟环境在多次运行间保持不变。
⌘↩ 在光标所在块上运行；⇧⌘↩ 将块发送到可分离的终端抽屉中用于交互式使用。
前置元数据键 cwd: 和 env: 定义笔记 shell 的起始目录和环境变量。
在 fence 中添加 norun 可禁用运行按钮，允许你引用命令而不执行它们。

"在纯 Markdown 中实现可运行的笔记是一种很棒的个人工具链优化——独自开发时，文档与终端之间的复制粘贴步骤大大减少。" – michaelastreiko (Hacker News)

远程主机执行与服务器支持的笔记

可将 Ledge 指向任何可通过 SSH 访问的机器；服务器存储 Markdown 文件并运行 shell。
无需单独账户或云服务——仅需 SSH 认证即可。
多个客户端（桌面、iPhone、iPad、另一台笔记本）可同时连接同一服务器，共享标签页和窗格。
ledge backup 每小时将笔记加密备份至 S3 兼容存储桶，提供自动异地备份。

移动端支持

iOS 和 Android 客户端作为远程服务器的轻量窗口；它们从不在本地存储笔记。
ledge pair 打印的配对码生成一个基于 Secure Enclave 的密钥，用于认证手机而无需暴露私钥。
所有常规编辑功能——搜索、标签、反向链接、每日笔记、维基链接——在移动端均可用，当你返回应用时，命令输出也会出现。

在任意主机上运行代码块

在前置元数据中添加 host: 行，可将所有块执行通过 SSH 路由至指定主机。
首次运行时，Ledge 会提示选择主机并记住上次的选择。
confirm fence 在执行前显示代码和目标主机，防止意外运行。
笔记的 cwd 和 env 随执行一起传递，确保敏感信息不暴露在笔记文件中。

基于窗格的 UI 与工作区布局

⌘D 垂直拆分视图；⇧⌘D 水平拆分。每个窗格拥有独立的标签页和笔记。
窗格保留各自的 shell 会话，因此你可以并行处理两个项目。
工作区布局在启动时自动保存和恢复；⌘1‑⌘9 可在已保存的工作区间切换。

安全配置文件与加密笔记

配置文件是存储在笔记文件夹外的普通 .env 文件（例如 ~/.config/ledge/profiles/deploy.env）。声明 profile: deploy 的笔记会将这些变量加载到其 shell 中。
加密笔记在磁盘上使用密码对正文进行加密；标题、标签和前置元数据仍可见，便于导航。
搜索和反向链接会跳过加密正文，报告有多少笔记被跳过。

与代理集成

Ledge 内置 MCP 服务器；像 Claude 这样的 AI 代理可通过 claude mcp add ledge 读取、搜索、创建和编辑笔记。
代理可执行 prompt 块，并接收 AI 响应流式显示在块下方。
由于笔记通过标题引用（标题在重命名后仍保持不变），代理可维持稳定的引用。

"我开发 Ledge 是因为我每天都要从笔记中复制命令到终端……我认为它对探索自己的工作流很有用，但我建议不要用于任何严肃的项目管理。" – Piraty (Hacker News)

基于 Git 的同步与协作

笔记是普通的 Markdown 文件；任何文件夹同步方案（iCloud、Dropbox、Syncthing、Git）均可开箱即用。
Ledge 监控文件夹中的外部变更，并实时更新打开的笔记。
专用的 Sync 笔记通过单次 ⌘↩ 执行 git add -A && git commit -m "notes $(date +%F)" && git pull --rebase && git push。
合并冲突以正常 Git 冲突形式出现；Ledge 保留打开的文件，将另一版本移至工作区回收站。

六种内置笔记类型

类型	典型用途	示例代码块
数据探索	快速 SQL 或 Python 查询	`sql` / `python` 块
项目运行手册	启动服务、运行迁移	包含 `docker compose up -d db` 的 `sh` 块
事件响应	查询日志、检查 Redis	`redis` 块
编程学习	小型语言片段	`ruby` 块
家庭实验室管理	在远程主机上运行命令	`host: homelab` + `sh` 块
每日日记	基于提示的任务列表	`prompt` 块

社区反馈

正面评价 – 用户称赞其文档与执行的无缝融合，指出复制粘贴摩擦的减少，尤其适合单人开发者和小型团队。
类比 – 多位评论者将 Ledge 比作 Org‑Babel、Jupyter 笔记本和 Observable Framework，但强调其原生 Markdown 格式和跨平台 GUI 是关键差异点。
批评与建议 – 用户请求更紧密的 shell 补全集成、笔记本风格的单元执行控制，以及潜在的 Obsidian 插件包装。
性能提示 – 有用户报告在高端 Linux 机器上出现 UI 卡顿，建议未来进行优化。

何时采用 Ledge.sh

DevOps 操作手册 – 将 API 密钥存于配置文件，运行部署脚本，并将日志保留在同一笔记中。
数据分析 – 在不离开笔记本的情况下混合使用 SQL、Python 和 shell 流水线。
AI 增强工作流 – 嵌入 prompt 块，将查询发送给 Claude 或其他代理，并在行内捕获响应。
以远程为主的工作团队 – 使用基于 SSH 的服务器模型，在笔记本、手机和 CI 运行器之间保持单一事实来源。

快速上手

# 在你希望托管笔记的任何机器上安装服务器组件
curl -fsSL https://ledge.sh/server.sh | sh

# 安装桌面客户端（macOS、Linux、Windows 通过 WSL）——详见 https://ledge.sh/docs/installation

安装完成后，创建一个 Markdown 文件，添加一个 fenced 代码块，将光标置于块内，按下 ⌘↩。输出将显示在块下方，笔记将自动同步到配置的服务器。

最后思考

Ledge.sh 将纯 Markdown 转变为一个跨桌面、移动端和远程主机的实时、可复现的笔记本，同时保持笔记为可使用 Git 进行版本控制的简单文件。其设计选择——每个笔记的持久化 shell、安全配置文件和代理集成——解决了现有笔记本和运行手册工具的诸多痛点，使其成为开发者、DevOps 工程师和 AI 增强工作流的有力选择。