本文详细介绍了如何利用 org mode 发布带有交互式图片画廊的网站。通过结合 org mode 的特殊块、自定义 emacs lisp 过滤函数以及外部 css/javascript 库，可以实现将简单的图片链接转换为功能丰富的画廊或轮播图。教程涵盖了从前端标记到后端处理和样式集成，为用户提供了灵活且专业的解决方案。
使用 Org Mode 发布交互式图片画廊
Org Mode 以其强大的文档管理和发布能力而闻名，但直接发布交互式图片画廊（如灯箱效果或图片轮播）并非其内置功能。然而，通过巧妙地结合 Org Mode 的可扩展性、Emacs Lisp 过滤函数以及前端 Web 技术，我们可以轻松实现这一目标。本教程将详细介绍构建一个可发布图片画廊的三大核心组件。
1. 定义图片画廊的特殊块
首先，我们需要在 Org 文件中定义一个清晰的结构来表示图片画廊。Org Mode 的特殊块（Special Blocks）是实现这一目的的理想选择。我们可以使用 #+BEGIN_gallery 和 #+END_gallery 来包裹一组图片链接。
Org 文件中的标记示例：
#+BEGIN_gallery [[file:images/test.png][测试图片]] [[file:images/psx.jpg][PlayStation]] [[file:images/IMG_1047.jpg][电话]] [[file:images/pants.png][裤子]] #+END_gallery
在这个示例中，每个图片都以 [[file:path/to/image.png][description]] 的形式表示。description 将作为图片的替代文本（alt attribute）或标题。这种标记方式简单明了，并且即使在没有 JavaScript 或 CSS 支持的浏览器中，也能优雅地降级为可点击的图片链接。
注意事项：
- 图片链接的格式可以根据需要调整，例如 [[file:full.png][file:thumb.png]] 可以用于指定独立的缩略图和完整图片。
- 关键在于 Org Mode 将这些链接转换为 HTML 后，我们能够对其进行进一步处理。
2. 实现 Org Mode HTML 过滤函数
Org Mode 在将 Org 文件导出为 HTML 时，会处理特殊块。我们可以通过编写一个 Emacs Lisp 过滤函数，在 Org Mode 默认处理特殊块之前，介入并修改其参数。这使得我们能够将简单的图片链接转换为包含缩略图和特定 CSS 类属性的 HTML 结构，以适配前端画廊库。
我们将使用 Emacs 的 advice 功能来过滤 org-html-special-block 函数的参数。
Emacs Lisp 过滤函数示例：
(defun my-html-gallery-links (args)
"过滤 Org Mode 画廊特殊块的参数，生成适配画廊库的 HTML 结构。"
(let ((special-block (nth 0 args))
(contents (nth 1 args))
(info (nth 2 args)))
(if (string= (org-element-property :type special-block) "gallery")
(progn
(with-temp-buffer
(insert contents)
(goto-char (point-min))
;; 查找图片链接并添加 class 和替换为缩略图
(while (re-search-forward "<a href="file://\(.*\)">" (point-max) t)
(let ((image_filename (match-string 1)))
(replace-match
(concat
"<a href=""
image_filename
;; 为 JavaScript 灯箱库设置 class
"" class="imagelightbox">"))
(backward-char 1)
;; 将链接描述替换为图片缩略图，并将描述移动到 alt 属性
(re-search-forward ">\(.*\)</a>" (point-max) t)
(replace-match
(concat
"><img src=""
"thumbs/" ; 假设缩略图存储在 'thumbs/' 目录下
image_filename
"" alt=""
(match-string 1)
"" /></a>"))))
(setq contents
(buffer-substring-no-properties (point-min) (point-max))))
(list special-block contents info))
args)))
;; 将过滤函数添加到 'org-html-special-block 的 :filter-args 建议中
(advice-add 'org-html-special-block :filter-args #'my-html-gallery-links)函数解析：
- my-html-gallery-links 函数接收 org-html-special-block 的参数。
- 它首先检查特殊块的类型是否为 "gallery"。
- 如果是 "gallery" 块，它会在一个临时缓冲区中处理块的原始内容（HTML 字符串）。
- re-search-forward 和 replace-match 用于查找形如 <a href="file://path/to/image.png">description</a> 的链接。
- 它将这些链接转换为 <a href="path/to/image.png" class="imagelightbox"><img src="thumbs/path/to/image.png" alt="description" /></a>。
- class="imagelightbox" 是为了与前端 JavaScript 库集成。
- src="thumbs/path/to/image.png" 假设存在一个 thumbs/ 目录存放缩略图。
- alt="description" 将原始链接的描述作为图片的替代文本。
- 最后，它返回修改后的内容，供 org-html-special-block 继续处理。
过滤前后的 HTML 对比：
过滤前：
<a href="images/IMG_1047.jpg">电话</a>
过滤后：
<a href="images/IMG_1047.jpg" class="imagelightbox"><img src="thumbs/IMG_1047.jpg" alt="电话" /></a>
高级用法提示： 这个过滤函数还可以进一步扩展，例如在发布过程中调用 imagemagick 等外部工具来自动生成缩略图、优化图片大小或去除元数据，从而简化发布流程。
3. 集成外部 CSS/JavaScript 画廊库
最后一步是引入一个前端 CSS/JavaScript 库来解析我们生成的 HTML 结构，并提供实际的画廊交互功能。市面上有许多优秀的库可供选择，例如 ImageLightbox、Lightbox2 或 Bootstrap Carousel 等。选择一个与你的标记结构兼容且功能丰富的库至关重要。
集成步骤：
-
准备静态资源： 将选定画廊库的 CSS 和 JavaScript 文件（例如 imagelightbox.js 和相关的 CSS 文件）放置在 Org 发布项目的静态资源目录中（例如 res/）。在 Org publish 项目配置中，这通常通过 :components 列表中的 :static 类型来处理。
(setq org-publish-project-alist '(("my-website" :base-directory "~/org/website/" :publishing-directory "~/public_html/" :components ("notes" "static")) ("notes" :base-directory "~/org/website/notes/" :base-extension "org" :publishing-directory "~/public_html/" :recursive t :html-extension "html" :body-only t ;; ... 其他配置 ... :html-head "<link rel="stylesheet" href="/res/org.css" type="text/css" /> <script type="text/javascript" src="/res/jquery-3.6.1.js"></script> <script type="text/javascript" src="/res/imagelightbox.js"></script> <script type="text/javascript"> $(function () { $( 'a.imagelightbox' ).imageLightbox(); }); </script>") ("static" :base-directory "~/org/website/res/" :base-extension "css\|js\|png\|jpg\|gif" :publishing-directory "~/public_html/res/" :recursive t))) -
在 HTML 头部引入资源和初始化脚本： 在 Org 发布项目的 :html-head 配置中，引入所需的 CSS 文件、JavaScript 库以及初始化画廊的脚本。
:html-head 配置示例：
<link rel="stylesheet" href="/res/org.css" type="text/css" /> <script type="text/javascript" src="/res/jquery-3.6.1.js"></script> <script type="text/javascript" src="/res/imagelightbox.js"></script> <script type="text/javascript"> $(function () { $( 'a.imagelightbox' ).imageLightbox(); }); </script>这个示例中，我们引入了自定义的 org.css、jQuery 库、imagelightbox.js，并在页面加载完成后（$(function () { ... });）初始化 ImageLightbox，使其作用于所有带有 imagelightbox 类的 <a> 标签。
选择画廊库的考虑：
- 标记兼容性： 确保所选库能够处理由我们的过滤函数生成的 HTML 结构。
- 功能需求： 是否需要灯箱效果、轮播、触摸支持、全屏模式等。
- 依赖性： 某些库可能依赖于 jQuery 或其他框架。
- 样式定制： 是否容易通过 CSS 进行样式调整。
关于轮播图（Carousel）风格： 本教程中的示例主要侧重于灯箱（Lightbox）风格的画廊。如果需要实现轮播图风格，你可能需要对 Org 标记和过滤函数进行微调，以生成轮播图库所需的特定 HTML 结构（例如，包裹图片的 div 元素和特定的 class/id 属性）。例如，Bootstrap Carousel 通常需要一个包含多个 div.carousel-item 的 div.carousel 结构。
总结
通过以上三个核心组件——Org Mode 特殊块定义、Emacs Lisp 过滤函数处理，以及外部 CSS/JavaScript 库集成，我们可以为 Org Mode 发布项目添加功能丰富且美观的图片画廊。这种模块化的方法不仅提供了高度的灵活性，也确保了内容与表现层的分离，使得维护和扩展都变得更加容易。记住，关键在于理解 Org Mode 的导出机制，并利用 Emacs Lisp 的强大功能来定制输出，从而与前端 Web 技术无缝对接。
