orgchange: 文学编程式 org mode 静态网页生成器

任何 org-export* 或 org-html* 变量都可以在 emacs-lisp org-block 里设置，例如：

(setq org-export-with-section-numbers t)

它们会在 emacs 执行 org-html-export-to-html 函数前被设置，这些选项可以放在全局 block 中也可以放在特定文章的 block 中，后者会在全局 block 代码执行完之后再执行，因此优先级更高。

以下列出可选参数的一部分以及它对应的 #+OPTIONS 缩写，更多请参考 emacs org mode 文档。

除此之外，由于 index org 里 emacs-lisp block 的代码都会被 emacs 执行，因此理论上可以在其中编写更复杂的代码，比如通过设置 org-export-before-parsing-hook 对 org 文件进行预处理、覆盖 org-html-template 函数结构等，这使得用户能为每篇文章都进行最精细的导出定制。

不过这类函数级别的修改更推荐写在每个主题的特定 elisp 文件中，并且留出控制的变量接口，这样在 index_org 中仍然只需要设定变量值来进行定制。

网站级别的选项涉及几大类： 前文说到 orgchange 先调用 emacs org-export 导出命令生成 html, 然后用 python 读取 html 并渲染出最终 的 html, 但这不是故事的全貌。由于 emacs 命令也是通过 python 调用的，因此 python 选项还能够决定一些更高层的设置，例如如果系统有多个 emacs 程序，可以指定特定版本的 emacs 来执行第一阶段导出

emacs = "~/codes/emacs-29.2/src/emacs" # 默认是 emacs, 自动寻找

这个设置不单可以是全局的，也可以针对特定文章，这样可以对比不同 emacs org 版本下的一些区别差别（尽管一般不会用到）

还包括前文提到的发布的目标文件夹，以及过滤前缀：

publish_folder = "~/codes/hugchangelife"
org_prefixes = ["~/org/logical", "~/org/design/web", "~/org/design/web/writing"]

另外网站主页 index.html 也是通过 jinja2 模板生成，因此许多展示在主页的信息也可以通过 python 变量来设置

# 可以指定不同 index 模版
index_template = "~/codes/hugchangelife/orgchange/themes/darkfloat/index.html"

beian = "粤ICP备2020003021"
github_url = "https://github.com/metaescape"
github_name = "oo"
site_repo = "https://github.com/metaescape/hugchange.life/"
author_name = "someone"
site_name = "Hugchange.life..."
site_email = "metaescape at foxmail dot com"
created_timestamp="2024-06-13 Thu 18:20" 
last_modify_timestamp="2024-06-13 Thu 18:20" 
html_lang = "zh" # "en"
feed_types = ["rss","atom"] #rss or atom or both
feed_num = 10 # 生成的 feed 中最新文章的数量

注意这些信息不单单会显示在主页，一般各个页面共享的 footer 或者 header 部分也可能继承（不同主题有不同基础样式，因主题而定），因此可以对每篇文章单独定制一些想要展示的信息。

以上提到的基本是全局设置，而由于 python 阶段会对 html 进行一些更精细的调整，因此这些文章级别的选项也由 python 来设置，例如：

link_replace = {"~/miniconda3/envs/torch2/lib/python3.11/site-packages/transformers":
                "https://github.com/huggingface/transformers/tree/main/src/transformers"}

这是一个字典，可以有多个值，每个元素的 key 是本地文件链接的前缀，value 是本地链接解析后 html 文件中希望展示的链接的前缀。它主要解决这样一类问题：在 org 中插入了一个本地的代码文件链接，这样可以通过 org 快速跳转并打开查看代码，但转换成 html 后本地文件地址对用户来说是无效链接，但如果该文件又是属于某个公开项目一部分，orgchange 就会根据 link_replace 里的规则对 html 里的路径进行替换，以展示公开的 url 链接。

另外，快速开始一节样例里提到的 categories 设置，这使得特定文章可以分别在 org 和 emacs 分类中找到。

categories = ["org", "emacs"]

再考虑这样的场景，你想写一系列算法和数据结构的文章，然后你希望在每篇在该系列中的文章的目录里，都可以看到同系列下其他文章的一级标题链接（类似 readthedocs 的全局目录），这样读者阅读完一篇之后， 可以从目录里看到该系列下的其他文章，那么只需要在 index_org 中对特定文章的 python 选项添加以下变量即可

anthology = "算法系列" # 相同合集的 org 文章会共享同一个目录

注意这与 categories 不一样，每篇文章只能属于一个系列（否则目录信息共享就会混乱了）。

考虑另外一个场景：你在 my_pyton_book.org 中记录了自己学习 python 的笔记，其中有多个章节，包括简介、语法基础、函数、面向对象四个一级标题，现在你想把它发布成一个多文件的 html, 那么可以给该文章添加 multipage_index 选项为 default, 如下图：

* my website :post:
** [[./my_python_book.org][ python 简易教程]]
#+begin_src python
 multipage_index = "default"  
#+end_src

此时 my_python_book.org 每个一级标题下内容会被导出一个单独的 html 文件， 统一放在 my_python_book 目录下：

mysite/my_python_book/
   - index.html # title 是简介
   - my_python_book_1.html # title 是语法基础
   - my_python_book_2.html # title 函数
   - my_python_book_3.html # title 是面向对象

这样，访问 mysite/my_python_book/ 目录会自动访打开 index.html, 也就是对应 org 文件中第一个标题下的内容，而这些 html 被默认看作是同一个 antholgy （合辑），每个 html 的目录中不单单只包括本文的章节索引，还会包括其他文章的标题索引。

其他选项说明及其说明如下：

#如果本文中有用 org-cite 或 org-ref 插入的文献，那么需要对本文指定 bib_info 才会将参考文献导出
bib_info = "~/org/lib/zotero.bib" 

# target_dir 是相对发布目录 publish_folder 的，相当于对特定文章继续指定一个子目录, 比如如果是 sysconfig, 那么文章会发布到 ~/codes/hugchangelife/sysconfig 下
target_dir = "sysconfig" 

# rainbow 是为了控制文章里导出的 lisp 系代码块里是否有彩虹高亮, 默认为 true
# 如果觉得眼花缭乱，可以改为 False, 也可以在全局设置
rainbow = False

本阶段从 index.org 中读取出所有需要发布的 blog 的信息，包括核心的 title 和路径等。

主函数是：

extract_site_info_from_index_org(index_org)

该函数找到 index_org 中第一个带有 "post" 的标题

1. 调用以下函数读取网页全局配置

   if "post" in node.tags and node.level == 1:
       site_info = update_site_info(node, site_info)
   

   update_site_info 会对带 "post" tag 的一级标题下的内容进行解析，首先提取出其中的代码块，当前主要是支持 elisp 和 python 块

   src_blocks = extract_code_blocks(node.get_body())
   for language, content in src_blocks:
       if language == "python":
           variable_setting = get_bindings_from_text(content["body"])
           site_info.update(variable_setting)
       if language == "emacs-lisp":
           site_info["user_elisp"] = content["body"]
   

   对于 python 块的内容，直接调用 get_bindings_from_text 把其中的赋值转成字典

   def get_bindings_from_text(args):
       exec(args)
       return {k: v for k, v in locals().items() if k != "args"}
   

   因此，如果配置中有一个 python 模块如下：

   github_url = "https://github.com/metaescape"
   github_name = "mE"
   site_repo = "https://github.com/metaescape/hugchange.life/"
   

   那么 site_info 当前就会变成：

   {
   "github_url" : "https://github.com/metaescape"
   "github_name" : "mE"
   "site_repo" : "https://github.com/metaescape/hugchange.life/"
   }
   

   对于其中的 elisp 代码块，则直接以字符串的形式保存到 site_info["user_elisp"] 中，这些字符串会直接拼接到 emacs 导出命令行里。比如假设有以下 elisp 代码

   (setq org-export-with-section-numbers t)
   

   那么 post_info 又继续更新成：

   {
   "github_url" : "https://github.com/metaescape"
   "github_name" : "mE"
   "site_repo" : "https://github.com/metaescape/hugchange.life/"
   "user_elisp" : "(setq org-export-with-section-numbers t)"
   }
   

2. 对 index org 中带 "post" tag 的一级标题下的每一个二级标题，执行 index_node_process 解析出每篇文章的发布信息。

   对于这些二级标题，如果带有 noexport 标签，那么整个子树不会被读取，如果带有 draft 标签，那么它会被认为是草稿， post_info["draft"] 为 True, 后文会根据该标签对其做特殊处理，一般来说 draft 不会显示在 index.html 的文章类表里（但这是可选的）。

   对于需要考虑发布的节点，解析该二级标题的过程和解析一级标题类似，比如都要去读取该标题下的 python 和 elisp 代码块，除此之外，还调用 post_title_path_prepare 去解析围绕该 org 文件的各种不同的路径：

   • org_path_abs2sys: org 文件在本机的绝对路径，这是发布的源路径，比如 "~/org/myblog.org"
   • html_path_abs2sys html 文件在本机的绝对路径，这是发布的目标，比如 "~/mywebsite/posts/myblog.org"
   • html_path_theoritical: html 文件所在的目录在本机的绝对路径，比如 "~/mywebsite/posts/"
   • html_path_rel2publish: html 相对于发布目录的相对路径，比如 "posts/myblog.org"
   • html_path_abs2www: 假设发布目录是根目录，那么 html 相对该目录的路径, 用于在 html 之间跳转， 比如 "/posts/myblog.org"

   这些路径在不同场合有不同的用处，比如该函数还会根据路径为 org_path_abs2sys 的 org 源文件是否比 路径为 html_path_abs2sys 的 html 目标文件的时间戳更晚，以决定是否要重新发布，如果要重新发布 post_info["need_update"] 会设为 True。为了能够实现如果 org 文件没有被修改，那么就不会重复导出的 cache 功能。

   对于二级标题，有一些常用的 python 选项如下：

   * my website :post:
   ** [[./my_first_blog.org][第一篇 blog]]
   #+begin_src python
    categories = ["emacs-org"] # 如果文中有 org-cite 或 org-ref 引用,需要指定 bib 文件
    bib_info = "~/org/lib/zotero.bib" # 添加标签
   #+end_src
   

3. need_update_propagate: 单篇文章是否要更新的策略：

   • 如果在 post tag 下的标题中第一个字符是 "-", 例如 [[./my_first_blog.org][-第一篇 blog]], 那么这篇 blog 会被强制更新，这通常是用来调试代码或者只是修改了 index_org 里文章选项但没有修改文章后使用。
   • 如果该 org 文件，如 my_first_blog.org 的最新修改时间比它对应的 html 文件如 my_first_blog.html 更新，那么需要更新。

   该文章周边文章更新策略：

   • 如果 2 号 blog 的修改了，但它是 draft, 那么不需要扩散，因为 draft 不会被其他文章的 prev 或 next 引用，因此不更新。 一种顾虑是与该 draft 在同一个 Anthology 的其他文章可能需要同步目录信息，但目前不考虑这种情况，因为如果该 draft 和其他非 draft 在同一个 anthology, 那么默认该文章是要尽快发布的。只有那些独占一个 anthology 的 draft 文章是作为一种存档形式长期以 draft 形式存在，这种文章也没有必要触发 propagate
   • 如果 2 不是 draft，那么在它前后的 blog 1 和 blog 3 的 prev/next 也可能需要更新，因此更新属性是会传染的。orgchange 缓存下了各个文件的 prev 和 next 文章标题和路径, 只有 prev 和 next 中 title 和 link 与上一次不同时才要真正进行更新。（这里默认在 index.org 中，两个非 draft 文章之间不会有 draft 文章，如果有请移动到 post section 的开头或者结尾）
   • 但如果 blog 1 或 2 是 draft, 默认 draft 不需要 prev/next, 因此不需要更新。

本环节核心代码如下：

for post_info in site_info["posts"]:
    for category in post_info.get("categories", []):
        if category == "":
            continue
        # distinguish with categories in post_info
        site_info["categories_map"][category].append(post_info)
    if post_info["need_update"]:
        publish_single_file(post_info, verbose)
        post_info["soup"] = get_soups([post_info["html_path_abs2sys"]])[0]

首先搜集各个文章的标签，然后对于需要更新发布的文件，调用 publish_single_file ，它调用 emacs 命令行，通过 python 字符串的 placeholder 功能把发布的文章地址、用户指定的 elisp 选项都注入到该命令行中，如下所示：

cmd = [
     "emacs",
     "--batch",
     f"--chdir={theme_path}",
     "--load",
     "../general.el",
     orgfile,
     "--eval",
     elisp_code,
     "--kill",
 ]
 process = subprocess.Popen(
     cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE
 )

注： ../general.el 是 orgchange/theme/general.el 文件，其中定制了一些 html 默认发布选项，比如使用 html5 标准等等，使得发布出来的 html 文件更加符合现代标准。

执行完该函数后会在 html_path_abs2sys 路径上生成一个 html 文件，该文件没有 css/js 支持，只是应用 emacs org 的默认 parser 和 export 工具把 org 文件内容导出成了 html, 下一个阶段就是读取 html 的各个部分并且填充到 jinja2 模版中。

如果导出的是 multipage 页面，也就是一个 org 导出成多个 html 文件的情况，那么导出后会额外调用 multipages_prepare 函数，实现前文介绍过的单 org 文件对应多 html 的功能。该函数还会把该 org 对应的所有子 post 的信息添加到 "multipages" 入口中：

post_info["multipages"] = posts

由 single_page_postprocessing(site_info) 来承载，该函数分成以下几个小环节：

最后一步，从主题目录下找到 index.html 和 category.html, categories.html 的 jinja2 模板，把 site_info 发送给它进行渲染。

• 首先在网页 header 部分（右上角）定义一个 html tag 如下：

  <div class="toggle-button">
      <input type="checkbox" id="theme-toggle" />
      <label for="theme-toggle"> </label>
  </div>
  

  这是一个 checkbox 类型的元素，因为它能够维持 1 bit 的状态用于区分是深色还是浅色模式

• 在 styles.css 中把该 <label> 元素调整成点击后左右滑动的样式（网络上很多现成实现，可以拷贝下来自己做小的修改） 这里要说明的是，在点击的视觉效果的实现上，css 都可以胜任，只是点击触发的逻辑需要以下的 js 代码来实现

• 在 /orgchange/themes/static/main.js 中，有 themeBtnHandler 如下

  function themeBtnHandler(targetTheme) {
    const toggleBtn = document.getElementById("theme-toggle");
    toggleBtn.addEventListener("change", () => {
      if (toggleBtn.checked) {
        setTheme("light");
      } else {
        setTheme("dark");
      }
    });
    toggleBtn.checked = targetTheme === "light";
  }
  

  该函数会在 main.js 中另外一处对 DOMContentLoaded 事件的触发逻辑中被调用，调用代码如下：

  themeBtnHandler(localStorage.getItem("theme"));
  

  这里从浏览器持久存储存储空间读取变量 theme, 当第一次打开网页时，该变量不存在，会默认读取到 null 值, 执行 themeBtnHandler 之后，对 theme-toggle 按钮的监听启动的，并且以下语句会导致 toggleBtn.checked 被赋予 False, 即 theme-toggle 按钮没有被勾选，也就不会触发按钮 change 事件，从而维持默认的主题(当前默认是 dark)

  toggleBtn.checked = targetTheme === "light";
  

• 当点击 checkbox 后，toggleBtn.addEventListener 监听到了 "change" 事件，这时候 toggleBtn.checked 已经变化了，因此触发 setTheme("light")

• 在 /orgchange/themes/static/main.js 对函数 setTheme 的定义如下

  function setTheme(targetTheme) {
    let oppsiteTheme = targetTheme === "light" ? "dark" : "light";
    var codeThemeCss = document.getElementById("code-theme-css");
    if (targetTheme === "dark") {
      codeThemeCss.href = "/orgchange/themes/static/dark.css";
    } else {
      codeThemeCss.href = "/orgchange/themes/static/light.css";
    }
  
    const html = document.documentElement;
    if (targetTheme === "dark") {
      html.classList.remove("light");
    } else {
      html.classList.add("light");
    }
    localStorage.setItem("theme", targetTheme);
    rootStyle = getComputedStyle(document.documentElement);
  
    parenBackground = rootStyle.getPropertyValue("--paren-background1").trim();
  }
  

  该函数内容被空行分成了三个部分：

  1. 选中 head 中 <link id="code-theme-css"> 元素，根据当前主题设置对应的 css 文件

  2. 如果是 light 主题，在 <html> tag 里加入 class="light", 在主风格文件 style.css 里有如下内容：

     :root {
       --heading-color: #e8e8e8;
       --toggle-width: 5rem;
       --toggle-height: 2rem;
       --change-decorate: rgb(0, 86, 143);
       ...
      }
     
      :root.light {
        --heading-color: #0c0c0c;
        /* --main-background: #c7b28a; */
        --main-background: #b7a17684 url(paperTexture.webp);
        --header-background: #b9a278;
       ...
      }
     

     这里 :root 对应的就是 <html>, 对 :root.light 的样式设置就是对 <html class="light"> 对象的修饰，而该元素包含了整个文档。因此整个文档里的 –heading-color 等变量被重新设置

  3. 从 root 里提取出 –paren-background1 变量赋值给一个全局的 parenBackground 变量，这用于修改修改 light 模式下彩虹括号背景色。

  以上三点基本覆盖了黑白主题之间涉及的所有变化。

这部分主要是参考 CSS Reset 网页，该 blog 的总体背景中，带有一点磨砂一样的纹理，作者是通过以下方式实现的：

• 先对容器设置背景

  background: var(--_1xn0dsy1q);
  

• 变量定义如下

  --_1xn0dsy1q: var(--_1xn0dsy1t);
  
  --_1xn0dsy1t: var(--_1xn0dsy8),linear-gradient(135deg,rgba(0,0,0,.6) 0%,transparent 60px),linear-gradient(to bottom,rgba(0,0,0,.6) 0%,transparent 80px),linear-gradient(to right,rgba(0,0,0,.5) 0%,transparent 20%),linear-gradient(to top,#000 0%,transparent 340px);
  
  --_1xn0dsy8: url(/images/noise.webp);
  

/images/noise.webp 是一个带噪点的透明背景图片，其尺寸是 100x100px, 大小是 2.7kb, 其中的渐变设置如下：

因此可以从 CodePen - Transparent Textures 或者 Transparent Textures 选择自己喜欢的透明纹理进行替换即可，以上网站下载下来的一般是 png, 如果想用 webp 可以在通过 PNG to WEBP | CloudConvert 进行转换。

另外，这种方式只能设置纹理，如果直接在纹理上写文字视觉效果会比较差，因此应该用以下两层 div 来包裹正文，最外面是 texture, 内层则设置纯颜色背景（带一点点透明使得纹理能够显现出来）

<div class="texture-background">
    <div class="pure-color-background">
      <h1>title</h1>
      <p> something </p>
    </div>
</div>

个人使用的是 emacs28.2+ ，对应 org 版本是9.5.5+，其 mathjax 的设置选项如下

<script type="text/x-mathjax-config">
    MathJax.Hub.Config({
        displayAlign: "center",
        displayIndent: "0em",

        "HTML-CSS": { scale: 100,
                        linebreaks: { automatic: "false" },
                        webFont: "TeX"
                       },
        SVG: {scale: 100,
              linebreaks: { automatic: "false" },
              font: "TeX"},
        NativeMML: {scale: 100},
        TeX: { equationNumbers: {autoNumber: "AMS"},
               MultLineWidth: "85%",
               TagSide: "right",
               TagIndent: ".8em"
             }
});
</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_HTML"></script>

主要问题是，该版本比较旧， 并且 cdnjs.cloudflare.com 几乎无法加载到，因此手动改成更新的版本，处理方法是，先在 general.el 里覆盖 org-html–build-mathjax-config 函数，如果检测到了有 latex 片段，不是插入 MathJax.js 引用，而是在 html 头里加一个 "need-mathjax" 的 placeholder 标签，如下：

(defun org-html--build-mathjax-config (info)
  "Insert the user setup into the mathjax template.
INFO is a plist used as a communication channel."
  (when (and (memq (plist-get info :with-latex) '(mathjax t))
	     (org-element-map (plist-get info :parse-tree)
		 '(latex-fragment latex-environment) #'identity info t nil t))
    "<script id=\"need-mathjax\"></script>"))

接着在 main.js 里加上检测该 id 对应的元素是否存在的代码，如果存在则加入 mathjax cdn 地址（如 bootcdn 或者本地缓存）和对应配置，具体参数见 /orgchange/themes/static/main.js。 这样做的好处是，单一篇文章已经发表很久了，此时想要更新 mathjax 的 cdn 地址，只需要修改 main.js 来更新, 完全不需要重新导出 blog 。

从 Mathjax | BootCDN 选择 js，其中提供了很多 Mathjax 的选项，AI 给出的选择标准是：

mathjax 会对原始的

\[
\lambda x.x x
\]

转换为：

<mjx-container class="MathJax" jax="CHTML" display="true" style="font-size: 117.1%; position: relative;">
  
  <mjx-math display="true" class="MJX-TEX" aria-hidden="true" style="margin-left: 0px; margin-right: 0px;">
    <mjx-mi class="mjx-i">
      <mjx-c class="mjx-c1D706 TEX-I"></mjx-c>
    </mjx-mi>
    <mjx-mi class="mjx-i">
      <mjx-c class="mjx-c1D465 TEX-I"></mjx-c>
    </mjx-mi>
    <mjx-mo class="mjx-n"><mjx-c class="mjx-c2E"></mjx-c></mjx-mo>
    <mjx-mi class="mjx-i" space="2"><mjx-c class="mjx-c1D465 TEX-I"></mjx-c></mjx-mi>
    <mjx-mi class="mjx-i"><mjx-c class="mjx-c1D465 TEX-I"></mjx-c></mjx-mi>
  </mjx-math>
  <mjx-assistive-mml unselectable="on" display="block">
    <math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mi>λ</mi><mi>x</mi><mo>.</mo><mi>x</mi><mi>x</mi></math>
  </mjx-assistive-mml>
</mjx-container>

因此如果要高亮某些 latex 对象，可以直接用 class name 方式

用户可以在 org 正文里通过以下两种方式添加 <scipt> 标签：

• #+BEGIN_EXPORT html 块里添加 script 或者 link, css, html 等，这被称为 html quote 。
• 在 js 或 css 代码块前添加 #+ATTR_HTML: :export css 或者 :export js, 这时候如果 src 代码块 确实是 css 或 js, 那么代码块会直接以 <style> 或者 <script> 形式导出，而非以 <pre> 或 <code> 形式。

• 在 js 或 css 代码块前添加 #+ATTR_HTML: :export both, 这时候如果 src 代码块 是 css 或 js, 那么代码块内容会以 <style> 或者 <script> 形式导出，同时以 <pre> 或 <code> 形式导出。 这样便于展示当前实现的 js 和 css 效果。

  ATTR_HTML 还支持：

  • :textarea 1 ： 将代码块转成可以输入的 textarea
  • :class classname ： 给代码块的 class="org-src-container" 层添加额外的 classname, 即变成 <div class="org-src-container classname"…>
  • :id idname ： 给代码块的 class="org-src-container" 层添加额外的 id, 即变成 <div class="org-src-container" id="idname"…>

而对于添加在 head 中的 <script> 会通过以下方式从 soup 中提取出来：

emacs_scripts = post_info["soup"].find("head").find_all("script")
if emacs_scripts:
    post_info["emacs_scripts"] = "\n".join(
        [str(script) for script in emacs_scripts]
    )

然后通过 jinja2 模板重新插入到 <head>, 这包括 mathjax 标签。

<head>
  <meta charset="utf-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>{{ title }}</title>
  {% include 'head.html' %} {{ emacs_scripts }}
</head>

但这同时意味着如果在 org 里用 ‘HTML_HEAD’ 或 ‘HTML_HEAD_EXTRA’ 添加的自定义的非 <script> 标签，如 <link> ，不会最终被添加到 jinja 模板中。

orgchange 使用 pygments 进行代码高亮，其原生就支持大量的主流编程语言，比如 python, css, bash 等

对于如下类型的 org src block 默认是没有语法高亮的，orgchange 将其看作 python 代码对待，因为其中的 *, #+ 等符号也是 python 里的特定语法对象，从而得到高亮。

* my website :post:
#+begin_src org
** [[./a1.org][ emacs 系列第一篇 ]]
#+end_src

源代码 block 的拷贝按钮是 js 动态生成的，点击后拷贝也是 js 实现

如下，页面加载之后，调用 addCopyCodeButtons 航速，它会扫描 html 所有 class 名为 ".org-src-container" 的元素（这是 org export to html 默认的代码块名称），然后像其中添加一个类名为 copy-code 的 button 元素，元素里内容是一个粘贴的 unicode 符号加上代码块语言名称（语言直接写在 <pre> 的类名中，dom.py 的 pygment_and_paren_match_all 函数对此有部分修改，比如把 jupyter-python 块的名称改为 python）， 并监听对该元素的 click 事件，如果点击则调用 copyCode 函数。

const copyLabel = "⎘ ";

function addCopyCodeButtons() {
  if (!navigator.clipboard) return;
  let blocks = document.querySelectorAll(".org-src-container");
  blocks.forEach((block) => {
    let button = document.createElement("button");
    pre = block.querySelector("pre");
    if (pre) {
      button.innerText = copyLabel + " " + pre.className;
    } else {
      button.innerText = copyLabel;
    }

    button.classList.add("copy-code");
    block.appendChild(button);
    button.addEventListener("click", async () => {
      await copyCode(block, button);
    });
    block.setAttribute("tabindex", 0);
  });
}
document.addEventListener("DOMContentLoaded", function (event) {
  addCopyCodeButtons();
});

copyCode 函数实现如下，这里主要就是调用浏览器提供的 navigator.clipboard.writeText(text); 提取 html 元素中的的文本到粘贴板，然后将 copy 按钮的内容临时改成 copied, 持续 0.5s 后还是回到语言名称来展示。

async function copyCode(block, button) {
  let pre = block.querySelector("pre");
  let text = pre.innerText;
  await navigator.clipboard.writeText(text);
  button.innerText = "copied";
  setTimeout(() => {
    button.innerText = copyLabel + " " + pre.className;
  }, 500);
}

在 styles.css 中则用 display: none; 使得 .copy-code 按钮内容默认不显示，只有鼠标放在代码框内才显示：

.org-src-container {
  position: relative;
  margin: 0 0;
}

.copy-code {
  display: none;
  position: absolute;
  top: 1rem;
  right: 1rem;
  background-color: #0000;
  border: none;
  border-radius: 5px;
  color: var(--heading-color);
}

.org-src-container:hover button {
  display: block;
}

如果有一个代码块是带 #+name 属性的，例如：

#+name: print_code
#+begin_src python
print(1)
#+end_src

org 在默认导出的时候是会删除这个属性的，但文章中有时会展示 noweb 形式的代码块引用且在 tangle 时不希望执行这些 noweb 引用，只希望是按类似如下的格式显示出来：

<<print_code>>

因此把 name 也在 html 中显示出来会比较方便

首先 org 有一个专门解析代码块的函数 org-html-src-block 函数，它的前几行内容如下：

(if (org-export-read-attribute :attr_html src-block :textarea)
    (org-html--textarea-block src-block)
  (let* ((lang (org-element-property :language src-block))

这里调用了一个 org-export-read-attribute 函数，它可以读取 attr, name 属性和 attr 很相似

#+ATTR_HTML: :width 800 :align center
#+NAME:

因此先尝试 (org-export-read-attribute :name src-block) 来读取 name, 但发现这里返回的是 plist, 之后查看 org-export-read-attribute 的实现，发现其中有用 org-element-property 函数继续去获取属性，而以上代码中也有用该函数读取 :language 属性，因此用以下方式：

(name (org-element-property :name src-block))

发现可以正常读取到 #+NAME 属性，于是把 name 加入到最终 <pre> 元素的构建中：

(format "%s<pre><code class=\"%s\"%s>%s</code></pre>"
        (if name (format "<div class=\"pre-name\">name: %s </div>" name) "")
        lang label code 
        )

最后加入 css 修饰：

.pre-name {
  color: var(--secondary-text-color);
  font-size: 1.2rem;
  transform: translate(1rem, 0.8rem);
}

在用户设置层面，如果要对文章进行导出，应在其 heading 下加入 bib_info 变量，这是一个元组，第一个是声明 bib 文件路径，第二个是文献导出的形式：

bib_info = "~/org/lib/zotero.bib", "ieee"
# bib_info = "~/org/lib/zotero.bib", "acl"

目前可用 acl 和 ieee 两种格式，分别是如下样式

acl 的引用格式
BERT 模型(Devlin et al., 2019)

acl 参考文献格式：
Jacob Devlin, Ming-Wei Chang, Kenton Lee, and Kristina Toutanova. 2019. BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding. In Proceedings of the 2019 Conference of the North American Chapter of the Association for Computational Linguistics: Human Language Technologies, Volume 1 (Long and Short Papers), pages 4171–4186, Minneapolis, Minnesota. Association for Computational Linguistics.

ieee 的引用格式
以 ChatGPT 为例[2],...

ieee 的参考文献格式：
[2] L. Ouyang et al., “Training language models to follow instructions with human feedback,” Advances in neural information processing systems, vol. 35, pp. 27730–27744, Dec. 2022, Accessed: Jan. 03, 2024. [Online]. Available: https://proceedings.neurips.cc/paper_files/paper/2022/hash/b1efde53be364a73914f58805a001731-Abstract-Conference.html

对于写 blog 已经足够了。

publish.py/bib_hook_parse 函数会读取 bib_info 变量，将其转换成以下字符串，这是 elisp 代码

f"""
(add-hook 'org-export-before-parsing-hook
(change/org-make-add-bibliography "{bib_file}" "{csl_file}" "{cite_style}"))
"""

publish.py/publish_single_file 函数中直接把以上命令插入到最终要执行的 emacs 命令中：

elisp_code = f"""
(progn 
    (setq default-directory "{html_folder}") 
    {post_info.get('user_elisp')}
    {bib_hook_parse(post_info)}
    {final_export_elisp})
"""

该命令执行时会调用定义在 general.el 中的以下 elisp 函数，把 #+cite_export: 、 #+bibliography: 和 #+print_bibliography 插入到 org 后再执行 export

(defun change/org-make-add-bibliography (bib-file csl-file-path csl-style-option)
  (lambda (backend)
    (save-excursion
      (goto-char (point-min))
      (re-search-forward "^#\\+title:" nil t)
      (forward-line)
      (let ((current-point (point)))
        (goto-char (point-min))
        (unless (re-search-forward "^#\\+bibliography:" nil t)
          (goto-char current-point)
          (insert (concat "#+bibliography: " bib-file "\n"))
          (insert (concat "#+cite_export: csl " csl-file-path " " csl-style-option "\n")))
        (unless (re-search-forward "^#\\+print_bibliography:" nil t)
          (goto-char (point-max))
          (insert "\n* 参考文献\n#+print_bibliography:"))))
          ))

由于 org-ref 插入的 citekey 和 org-cite 的不一样，但导出时用的是 org 自带的 org-cite 中的导出模块，因此要在 export 前先把 org-ref 格式转成 org-cite 形式，以下函数加入到导出前的 hook 中来解决这个问题。

(defun change/org-modify-cite-links (backend)
  "Modify cite links in the current buffer for export."
  (goto-char (point-min))
  (while (re-search-forward "\\[\\[cite:&\\(.*?\\)\\]\\]" nil t)
    (unless (org-between-regexps-p "^#\\+begin_" "^#\\+end_")
      (replace-match "[cite:@\\1]" nil nil))))

(add-hook 'org-export-before-parsing-hook 'change/org-modify-cite-links)

对于 multipage, 我希望的是：

• 第一个 heading 会转换成 index.html, title 为 heading 内容， subtitle 为 #+tiltle/0
• 第二个 heading 会转换成 folder_name_1.html, title 为 heading 内容， subtitle 为 #+tiltle/1
• 以此类推

** CSS 中接近通用编程语言的部分

以上是 org 文件中一个二级标题，导出成 html 后是一个三级标题，如下：

<h3 id="org9273cf1">CSS 中接近通用编程语言的部分</h3>

但这有两个不足：

• html 标题无法点击，需要转成以下形式：

  <a href="#org9273cf1">
    <h3 id="org9273cf1">CSS 中接近通用编程语言的部分</h3>
  </a>
  

  这通过设置 org-html-self-link-headlines 为 t 实现，该值默认是 nil, orgchange 中修改为默认是 t, 如果不需要，可以在 org index 的 emacs lisp 代码块中设置其为 nil 。

• id 是随机生成的，一次再小的修改都会导致所有 id 变化，不利于 git 对比差异，也不利于链接分享。

  导出时添加以下方式实现：

  (defun org-export-deterministic-reference (references)
      (let ((new (length references)))
         (while (rassq new references) (setq new (+ new 1))) 
         new))
  (advice-add #'org-export-new-reference :override #'org-export-deterministic-reference)
  

  参考： Export to HTML with useful, non-random IDs and anchors : r/orgmode

如果当前代码块是以下之一，同时页面变量 rainbow 为 True （默认为 True） 那么会调用 paren_match 算法来提取出括号，并且按括号的深度层级打上标签，这基本是一个基于栈的解析算法。

lisp_family = [
    "scheme",
    "lisp",
    "racket",
    "elisp",
    "emacs-lisp",
    "elisp",
    "jupyter-python",
]

org 原生导出成 html 的原理可以参考 include-yy 博客里的 The Org Manual 13.9 全解 和 语义元素与 org 的 html5 导出 等几篇与 org 导出有关的（非常细致）的文章。对 org-export 流程有了一个总体了解之后就可以带着具体的问题（比如如何能导出 org 代码的 #+name 标签）在 emacs 中直接查看相关函数的源码并针对自己想要修改或添加的功能做一些尝试。

对我来说，最初对 jinja2 的理解困难更多是概念上带来的，因为以前从来没接触过一种混在某种结构文本里的编程语言，甚至不知道这到底是用来做什么的，似乎没有什么必要。但用 python fstring 来作为类比可以很快越过概念理解的障碍。 jinja2 的模版可以看成是 python fstring 的扩充版本，当你需要打印某个字符串，但其中部分字符串是来自变量值或表达式结果时，就会用到 fstring

a = 1
b= 2
f"{a} + {b} = {a+b}"

1 + 2 = 3

然而对于个人 blog 网页来说， html 里大部分其实是文章内容，而 html 只是一个框架。比如，每篇 blog 都有一个一级标题，而标题就在各个 org 或者 markdown 文件中，因此当从 org/md 里读取到了标题之后，就可以通过以下方式来生成 html:

def render_blog(title):
    html = f"""<h1>{title}</h1>"""
    return html
    
for title in ["第一篇文章", "2022 总结"]:
    print(render_blog(title))

<h1>第一篇文章</h1>
<h1>2022 总结</h1>

当然实际中每篇文章不止有标题，但其他内容也是这样被填充到 fstring 模版里的， jinja2 把这些模版提取出来，封装成更方便且功能更丰富的接口（比如模版之间的继承、在模版里写 for 循环等）。

有了这层类比之后，对于 jinja2 的具体细节就可以查看文档或者 flask 教程里关于 jinja2 的部分。

在开发完这个包的基本功能之后，我发现了同样基于 python 的静态网页生成器 pelican, 它主要适用于对 Markdown 和 reStructuredText 的解析，它提到的几个功能和 orgchange 都很相似，比如：

• Site themes (created using Jinja2 templates)
• Code syntax highlighting via Pygments

因为 pelican 是个多人参与并相对成熟的项目，其中有大量的额外的插件，后续可以考虑使得 orgchange 能够支持其生态中的部分插件，比如 rss 生成，全站搜索等等。