本博客技术备忘

Github Pages默认使用Jekyll构建，也可以通过github actions支持其他的构建方案，或者直接把构建好的网站push到repo。

本博客目前使用github-pages gem，它固定了jekyll和一些其他包的版本。本文简单做一些记录备忘。

构建

jekyll使用ruby技术栈，一般用Bundler做gems的依赖管理。

$ bundle env # 输出环境信息
# bundle 默认会安装到系统目录，下面命令设置为gem默认的用户目录。
$ bundle config set --global path ~/.gem/ # 会更新 ~/.bundle/config 文件
# bundle 替换为国内源：
$ bundle config set --global mirror.https://rubygems.org https://mirrors.tuna.tsinghua.edu.cn/rubygems
$ bundle install # gems及依赖 会安装到上面path指定的目录

$ bundle exec jekyll serve

org-mode

Emacs下org-mode的功能比md更强大，有些文档可以使用org-mode来编辑。希望org-mode编写部分文档，同时可以和jekyll渲染的文档保持观感一致，例如复用主题等。

参考了一些文档：

大致方案是利用org-mode的publish功能，把org-mode的文档publish为html格式到对应目录。org-mode的文档保留jekyll的front matter。具体见.dir-locals.el。

需要注意，org文档关闭默认的toc,然后在合适位置插入需要的TOC，否则front matter就不在第一行，jekyll不会正确处理。

#+OPTIONS: toc:nil
#+TOC: headlines 2

org mode里使用dot

参考：https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-dot.html

一些tips：

使用 ordering=out 可以保留输入的顺序。例如在二叉树中，左孩子和右孩子的顺序是有意义的。
add caption to images generated by a code block

beamer制作幻灯片

org-mode导出pdf幻灯片：

M-x: org-beamer-export-to-pdf

中文需要以下两个配置

#+LATEX_HEADER: \usepackage{ctex}
#+latex_compiler: xelatex

beamer默认字体是sans serif字体，修改字体：

\setsansfont{Liberation Serif}
#+LATEX_HEADER: \setCJKsansfont{SimSun}

一些参考：

导出为html时生成的div id一直变化

org-mode-publish会给Headings等生成crossrefs，并缓存在本地的.org-timestamps/目录下。在.org文档的相关部分没做修改的情况下，包含在crossrefs中的id可以保持不变。(前提是可以访问到之前的缓存)。但是其他的id会一直变化，如special block。主要相关代码：

org-export-new-reference
org-export-get-reference

没有找到好的方案可以保留之前的id。完整解决需要修改orgmode生成html的逻辑。暂时用的方案为：使用如下代码，在生成的html中删除掉id字段。没有全部删除是因为Headings等生成的id有时候还是有用的，而且在上面提到的可以获取到之前生成的crossref的情况下，这些id会保留。

(defun org-html-body-remove-id (output)
  "Remove random ID attributes generated by Org."
  (replace-regexp-in-string
     " id=\"[[:alpha:]-]*org[[:alnum:]]\\{7\\}\""
     ""
     output t))
(advice-add 'org-html-special-block :filter-return #'org-html-body-remove-id)
(advice-add 'org-html-paragraph :filter-return #'org-html-body-remove-id)

theme / css

居中图片 https://emacs.stackexchange.com/questions/41534/alignment-of-images-in-html-export 在orgmode文档开头添加 #+HTML_HEAD_EXTRA: <style> .figure p {text-align: right;}</style>

但是publish到jekyll中，用了body-only，没有上面的header。可以在jekyll的main.scss中添加
```
.figure p {text-align: center;}
```
org mode下，begin_NAME end_NAME块生成class 为NAME的div。例如bengin_NOTE end_NOTE在main.scss里定义.note .NOTE的style，可以简单继承自blockquote。
```
.note, .NOTE {
    @extend blockquote;
}
```

用`pandoc`从md生成其他格式文件

有些文档，除了生成网站，也可能单独拿出来另作他用。可以用pandoc命令转换文档格式。 tools/md2pdf给除了一个简单脚本，使用pandoc命令生成pdf.

pandoc和jekyll 渲染不同的内容

<!--
{% comment %}
-->
pandoc 显示但jekyll不显示的内容

<!--
{% endcomment %}
-->


<!--
{% comment %}
-->
```{=ignore}
<!--
{% endcomment %}
-->
jekyll 显示但pandoc不显示的内容

<!--
{% comment %}
-->
```
<!--
{% endcomment %}
-->

```

构建