Org Mode 发布自定义图片画廊教程_技术教程

本教程详细阐述了如何利用 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 "" (point-max) t)
                 (setq image_filename (match-string 1))
                 (replace-match
                   (concat
                     ""))
                 (backward-char 1)
                 ;; 将文本描述替换为图片缩略图，并将描述移至 alt 属性
                 (re-search-forward ">\\(.*\\)\" (point-max) t)
                 (replace-match
                   (concat
                     ">@@##@@")))
          (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 默认生成）:
```
电话
```
过滤后（经过 my-html-gallery-links 处理）:
```
@@##@@
```

注意事项：

缩略图路径：示例中假设缩略图位于 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 属性将和

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 "


"
          :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 文件，其中可能包含画廊的样式。
：引入 jQuery 库，ImageLightbox 依赖它。
：引入 ImageLightbox 库文件。
：这是 ImageLightbox 的初始化代码。它在 DOM 加载完成后，选择所有带有 imagelightbox 类的标签，并对其应用 ImageLightbox 功能。

画廊类型适配：

本教程的示例侧重于灯箱（Lightbox）效果。如果您希望实现轮播（Carousel）效果，例如 Bootstrap Carousel，您需要调整过滤函数生成的 HTML 结构以符合该库的要求。通常，这意味着将图片链接包裹在特定的 div 元素中，并添加相应的 class 和 id 属性。例如，Bootstrap Carousel 可能需要以下结构：

  
    
      @@##@@
    
    
      @@##@@

您的过滤函数就需要生成这样的 div 结构，而不是简单的组合。这展示了 Emacs Lisp 过滤函数的高度灵活性，可以根据任何前端库的需求进行定制。

总结

通过上述三个步骤——定义 Org Mode 特殊块、编写 Emacs Lisp 过滤函数和集成外部 CSS/JavaScript 画廊库——我们成功地为 Org Mode 静态网站发布功能添加了自定义图片画廊的能力。这种方法充分利用了 Org Mode 的可扩展性，允许用户在保持 Org 文档简洁性的同时，实现复杂且富有交互性的网页元素。

关键考量点：