Show HN: 简易 org-mode Web 适配器

Source: Hacker News

Org Web 适配器

一个轻量级的本地 Web 应用，用于浏览和编辑 Org 文件。

该应用实现为一个 Python 服务器（main.py）以及一个 HTML 模板（templates/index.html）和一个样式表（static/style.css）。它会扫描笔记目录中的 .org 文件，并呈现一个三窗格 UI。

⚠️ 此服务没有身份验证或加密；请仅在受信任的网络上运行。 ⚠️

截图

桌面

移动

指令

• 将你的 notes 目录符号链接到 notes。
• 如有需要，可编辑 config.yaml 中的绑定地址和端口。
• 运行服务器：

python3 main.py

工作原理

• main.py 启动一个 HTTP 服务器。
• 在每次页面请求 (GET /) 时，它会重新扫描 notes 目录中的 .org 文件。
• 它解析链接/反向链接并构建 HTML 片段。
• 这些片段被注入到 templates/index.html 的占位符中：
  • {{NAV_ITEMS}}
  • {{MAIN_CONTENT}}
  • {{BACKLINKS}}
• templates/index.html 中的浏览器 JavaScript 负责客户端交互（搜索、随机、排序、跳转到当前、主题切换）。

Server‑side components (main.py)

文件发现与解析

• scan_org_files(...) 递归查找 .org 文件。
• 从 #+TITLE: 提取标题，从 :ID: 提取 ID。

Org 链接/反向链接处理

• resolve_link_target(...) 支持 file:... 和 id:... 链接。
• find_backlinks(...) 计算链接到所选笔记的其他笔记。
• build_backlink_counts(...) 计算反向链接总数以便排序。

渲染

• render_org_to_html(...) 将标题（*、** …）和段落转换为简易 HTML。
• render_line_with_links(...) 将文本中的 Org 链接转换为可点击的应用链接（如果可解析）。
• truncate_label(...) 将侧边栏标签限制为 32 个字符，并以 … 结尾。

编辑

• POST /edit 更新选定的 .org 文件，并带状态标记重定向回去。

静态文件

• serve_static(...) 在 static/ 目录下提供文件服务，并实现路径遍历保护。

前端组件

templates/index.html

• 基础布局标记。
• 侧边栏控件。
• 用于过滤、排序和随机排列导航链接的小型 JavaScript 控制器。
• MathJax 初始化，以渲染内联 $...$ 公式。

static/style.css

• 三列桌面网格和堆叠的移动端布局。
• 笔记列表和反向链接的独立滚动区域。
• 移动端笔记列表上限（约显示五条笔记后出现滚动）。

配置

启动配置默认从 config.yaml 读取。

• bind_addr：要绑定的主机/IP。
• bind_port：TCP 端口（1..65535）。

如果 config.yaml 缺失，默认使用 127.0.0.1:8000。

CLI 标志 --host 和 --port 会覆盖配置中的值，--config /path/to/config.yaml 允许您指定其他配置文件。

有用的运行命令

python3 main.py --dir notes
python3 main.py --host 127.0.0.1 --port 9000
python3 main.py --config ./config.yaml
python3 main.py --no-browser

功能

笔记浏览

• 递归发现 .org 文件。
• 侧边栏笔记列表，突出显示当前笔记。
• 标题/路径搜索过滤。

侧边栏排序控制

• 随机排列笔记。
• 按反向链接数量排序（降序）。
• 按创建日期排序（升序）。没有时间戳的笔记视为比有时间戳的笔记更旧。
• 跳转到当前笔记按钮。

反向链接

• 右侧栏列出链接到当前笔记的笔记。
• 支持 file: 和 id: 链接解析。

编辑

• 切换所选笔记的预览/编辑模式。
• 将更改从浏览器保存到磁盘。
• 内联状态信息，显示保存成功或错误。

数学渲染

• 使用 MathJax 通过 $...$ 分隔符进行行内数学渲染。

UI 行为

• 明暗主题切换（持久化存储于 localStorage）。
• 桌面端：独立可滚动的侧边栏。
• 移动端：笔记列表有独立的滚动区域。
• 侧边栏文本截断显示省略号，悬停提示完整文本。

项目布局

• main.py：服务器、解析、渲染、路由。
• templates/index.html：页面模板 + UI 行为 JavaScript。
• static/style.css：样式和响应式布局。
• config.yaml：绑定配置。
• notes/：笔记目录（可以是符号链接）。
• old_notes/：备用本地笔记快照。

限制

• 不是完整的 Org 解析器；渲染故意保持简洁。
• 笔记在每次请求时都会重新扫描（简单且最新，但对大规模笔记集未进行优化）。
• 数学渲染依赖于从 CDN 加载 MathJax。