本教程详细阐述了如何利用 org mode 发布功能，通过结合特殊块定义、emacs lisp 过滤函数以及外部 css/javascript 画廊库，创建并发布自定义图片画廊。文章将指导读者完成从 org 标记到最终 html 结构的转换，并提供代码示例及集成步骤，帮助用户实现高度定制化的图片展示效果，提升静态网站的交互性与视觉吸引力。
Org Mode 发布图片画廊的实现策略
Org Mode 是一款强大的结构化文档编辑工具，其发布功能使其成为生成静态网站的理想选择。然而，直接通过 Org Mode 发布复杂的图片画廊（如灯箱效果或图片轮播）并非其核心功能。本文将介绍一种灵活且可扩展的方法，通过定义 Org Mode 特殊块、编写 Emacs Lisp 过滤函数来转换 HTML 结构，并集成外部 CSS/JavaScript 画廊库，从而在 Org Mode 发布过程中实现自定义图片画廊。
这种方法的优势在于其模块化和高度可定制性，允许用户根据所选画廊库的需求精确控制最终的 HTML 输出。整个过程可分为三个主要步骤：
- 定义 Org Mode 特殊块：用于在 Org 文档中标记图片画廊区域。
- 实现 Emacs Lisp 过滤函数：将 Org Mode 生成的默认 HTML 结构转换为画廊库所需的特定标记。
- 集成外部 CSS/JavaScript 画廊库：引入前端库以提供交互式画廊功能。
第一步：定义 Org Mode 特殊块
为了在 Org 文档中清晰地标识图片画廊内容，我们可以利用 Org Mode 的特殊块（Special Blocks）功能。这不仅提高了文档的可读性，也为后续的 HTML 转换提供了明确的边界。
Org 标记示例：
#+BEGIN_gallery [[file:images/test.png][测试图片]] [[file:images/psx.jpg][PlayStation]] [[file:images/IMG_1047.jpg][电话]] [[file:images/pants.png][裤子]] #+END_gallery
在这个示例中，我们使用 #+BEGIN_gallery 和 #+END_gallery 来包裹一组图片链接。每个链接包含图片路径和描述文本。这种简洁的标记方式有以下优点：
- 语义清晰：明确指出这是一个图片画廊。
- 向后兼容性：即使在没有 JavaScript 或 CSS 的浏览器中，这些链接也能作为普通图片链接和文本描述正常显示，提供良好的用户体验降级。
- 灵活性：可以根据需要选择不同的图片链接格式，例如 [[file:images/test.png]]（仅图片）或 [[file:images/full.png][file:images/thumb.png]]（全尺寸图与缩略图分离），但对于本教程的过滤函数，我们选择 [[file:images/path/image.jpg][描述文本]] 的形式。
第二步：实现 Emacs Lisp 过滤函数
Org Mode 发布过程会将其特殊块内容转换为 HTML。为了使这些 HTML 片段符合特定画廊库的要求，我们需要一个过滤函数来修改 Org Mode 默认生成的 HTML。这里，我们通过 Emacs Lisp 的 advice 机制来增强 org-html-special-block 函数，使其在处理 gallery 类型特殊块时执行自定义转换。
过滤函数的核心作用是：
- 识别 gallery 特殊块。
- 解析其内部的 HTML 内容（Org Mode 已经将 [[file:images/test.png][测试图片]] 转换为 测试图片）。
- 将这些链接转换为画廊库所需的特定结构，例如添加 CSS 类、将文本描述转换为
标签的 alt 属性，并将缩略图路径插入到
标签的 src 属性中。
Emacs Lisp 过滤函数示例：
(defun my-html-gallery-links (args)
(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))
;; 查找并修改链接，添加 imagelightbox 类
(while (re-search-forward "<a href="file://\(.*\)">" (point-max) t)
(setq image_filename (match-string 1))
(replace-match
(concat
"<a href=""
image_filename
;; 设置 class 以供 JavaScript 灯箱库使用
"" 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 的参数，包括特殊块对象、其内容和 Org 导出信息。
- 它检查特殊块的类型是否为 "gallery"。
- 如果是 gallery 块，函数会在一个临时缓冲区中操作其 HTML 内容：
- 第一个 re-search-forward 查找 形式的链接。file:// 是 Org Mode 在导出时为本地文件路径添加的前缀，需要注意匹配。
- replace-match 将链接的 href 属性修正为相对路径，并添加 class="imagelightbox"，这是许多灯箱库识别图片链接的方式。
- 第二个 re-search-forward 查找链接内部的文本描述（例如 >测试图片）。
- replace-match 将文本描述替换为
标签，其中 src 属性指向缩略图路径（这里假设缩略图位于 thumbs/ 目录下），alt 属性则使用原始的文本描述。
- 最终，函数返回修改后的特殊块内容，Org Mode 将使用这些内容进行发布。
HTML 转换前后对比：
-
过滤前（Org Mode 默认生成）:
<a href="images/IMG_1047.jpg">电话</a>
-
过滤后（经过 my-html-gallery-links 处理）:
<a href="images/IMG_1047.jpg" class="imagelightbox"><img src="thumbs/IMG_1047.jpg" alt="电话" /></a>
注意事项：
实现 Markdown↔ HTML 互转，支持导出 PDF，用于用户请求的文档格式转换。
- 缩略图路径：示例中假设缩略图位于 thumbs/ 目录下。您需要确保这些缩略图文件实际存在于该目录中，并且在发布时被正确复制到目标网站。更复杂的过滤函数甚至可以集成 ImageMagick 等工具，在发布过程中自动生成缩略图。
- 正则表达式：请根据您 Org Mode 导出设置和图片链接的具体格式调整正则表达式，确保准确匹配。
第三步：集成外部 CSS/JavaScript 画廊库
最后一步是引入一个前端画廊库，来解析我们生成的 HTML 结构并提供交互功能。市面上有许多优秀的画廊库可供选择，例如 Lightbox、ImageLightbox、Bootstrap Carousel 等。本教程以 Osvaldas' ImageLightbox 为例，因为它轻量且易于集成。
集成步骤：
- 下载库文件：将 ImageLightbox 的 JavaScript (imagelightbox.js) 和 CSS 文件 (imagelightbox.css，或自定义样式) 下载到您的 Org Mode 项目的静态资源目录中（例如 res/）。
-
配置 Org Mode 发布项目：在您的 Org Mode 发布项目配置中，需要做两件事：
- 复制静态资源：确保 imagelightbox.js、jquery-3.6.1.js（ImageLightbox 依赖 jQuery）和您的自定义 CSS 文件被复制到发布目录。这通常通过 :components 属性来完成。
- 注入 HTML 头部代码：使用 :html-head 属性将 和 <script> 标签注入到每个生成页面的 <head> 部分。</script>
Org Mode 发布配置示例 (org-publish-project-alist 中的 :html-head 部分):
(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"
: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>"
:exclude "private.org")
("static"
:base-directory "~/org-website/res/"
:base-extension "css\|js\|png\|jpg\|gif\|svg"
:publishing-directory "~/public_html/res/"
:recursive t
:exclude "tmp.txt"))))html-head 代码解析：
- ：引入您的自定义 CSS 文件，其中可能包含画廊的样式。
- <script type='"text/javascript"' src="%5C%22/res/jquery-3.6.1.js%5C%22"></script>：引入 jQuery 库，ImageLightbox 依赖它。
- <script type='"text/javascript"' src="%5C%22/res/imagelightbox.js%5C%22"></script>：引入 ImageLightbox 库文件。
- <script type='"text/javascript"'> $(function () { $( 'a.imagelightbox' ).imageLightbox(); }); </script>：这是 ImageLightbox 的初始化代码。它在 DOM 加载完成后，选择所有带有 imagelightbox 类的 标签，并对其应用 ImageLightbox 功能。
画廊类型适配：
本教程的示例侧重于灯箱（Lightbox）效果。如果您希望实现轮播（Carousel）效果，例如 Bootstrap Carousel，您需要调整过滤函数生成的 HTML 结构以符合该库的要求。通常，这意味着将图片链接包裹在特定的 div 元素中，并添加相应的 class 和 id 属性。例如，Bootstrap Carousel 可能需要以下结构：
<div id="myCarousel" class="carousel slide" data-ride="carousel">
<div class="carousel-inner">
<div class="carousel-item active">
<img src="path/to/image1.jpg" alt="描述1">
</div>
<div class="carousel-item">
<img src="path/to/image2.jpg" alt="描述2">
</div>
<!-- 更多图片 -->
</div>
<!-- 导航按钮等 -->
</div>您的过滤函数就需要生成这样的 div 结构，而不是简单的 组合。这展示了 Emacs Lisp 过滤函数的高度灵活性，可以根据任何前端库的需求进行定制。
总结
通过上述三个步骤——定义 Org Mode 特殊块、编写 Emacs Lisp 过滤函数和集成外部 CSS/JavaScript 画廊库——我们成功地为 Org Mode 静态网站发布功能添加了自定义图片画廊的能力。这种方法充分利用了 Org Mode 的可扩展性，允许用户在保持 Org 文档简洁性的同时，实现复杂且富有交互性的网页元素。
关键考量点：
- 文件管理：确保所有图片（包括缩略图和全尺寸图）以及 JavaScript/CSS 资源都正确地放置在发布目录中。
- 性能优化：对于大量图片，考虑对图片进行优化（压缩、尺寸调整），甚至在过滤函数中集成图片处理工具来自动化此过程。
- 用户体验：始终考虑无 JavaScript 或无 CSS 时的用户体验降级方案，确保内容仍然可访问。
掌握这种定制化发布流程，将极大地拓宽您使用 Org Mode 构建功能丰富静态网站的可能性。
