如何使用 org-mode 发布博客

1. 背景
2. 开始
3. 主题
- 3.1. 简单配置
- 3.2. 高级配置
  - 3.2.1. 定制样式
4. 参考

1. 背景

最近想建一个简单的个人站点，尝试了一些方案后，发现使用 org 文件直接生成博客的方案非常的方便（markdown 文件生成博客的方案其实也很方便，不过个人更熟悉 org-mode 些），所以今天就讲讲如何使用 org-mode 来生成个人博客。

2. 开始

运行环境

emacs 29.1
spacemacs @develop 2024/1/30

spacemacs 开启 org layer

(setq-default dotspacemacs-configuration-layers '(org))

2.1. 介绍

本次使用的包是 ox-publish , spacemacs 中已经内置了该包我们无需额外安装。我们主要使用该包中将 org 文件转换成 html 文件的功能。

2.2. 基础

假设 org 文件存放于 ~/org, 发布目录为 ~/www

2.3. 发布第一个项目

org 发布的所有配置都由变量 org-publish-project-alist 来配置, spacemacs 中可以在 user-config 中进行配置，如下所示:

(setq org-publish-project-alist
      '(

        ;; ... add all the components here (see below)...

        ))

2.3.1. Note 组件

该组件定义了我们的 org 文件如何转换为 html 文件，当然这里的配置非常多，下面列的只是最基本的一些。

("org-notes"
 :base-directory "~/org/"
 :base-extension "org"
 :publishing-directory "~/www/"
 :recursive t
 :publishing-function org-html-publish-to-html
 :headline-levels 4             ; Just the default for this project.
 :auto-preamble t
 )

该组件包含如下几个参数：

:base-directory 组件根目录，指向源文件所在目录，即 org 文件所在目录
:base-extension 文件扩展名，这里为 org
:publishing-directory 文件导出目录，这里最终生成的 html 文件的目录
:recursive 是否递归查找子目录
:publishing-function 发布使用的函数
:headline-levels 标题的尝试
:auto-preamble ？？这个参数没有找到说明

2.3.2. Static 组件

该组件定义了我们的一些静态的文件应该如何处理。

("org-static"
 :base-directory "~/org/"
 :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf"
 :publishing-directory "~/www/"
 :recursive t
 :publishing-function org-publish-attachment
 )

这里的参数基本和 Note 组件差不太多，不过这里的发布函数是 org-publish-attachment 区别是不会对文件做转换，只是按目录拷贝到目标文件夹

2.3.3. publish 组件

这个组件其实就是将 Note 组件及 Static 组件组合在一起，其实也就是完整的发布流程了。

("org" :components ("org-notes" "org-static"))

:components 该参数用于传入需要引用的组件

2.3.4. 完整的配置

(setq org-publish-project-alist
      '(

        ;; ... add all the components here (see below)...
        ("org-notes"
         :base-directory "~/org/"
         :base-extension "org"
         :publishing-directory "~/www/"
         :recursive t
         :publishing-function org-html-publish-to-html
         :headline-levels 4             ; Just the default for this project.
         :auto-preamble t
         )
        ("org-static"
         :base-directory "~/org/"
         :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf"
         :publishing-directory "~/www/"
         :recursive t
         :publishing-function org-publish-attachment
         )
        ("org" :components ("org-notes" "org-static"))
        ))

此时按快捷键 M-x 选择 org-publish / org ，已经可以正常运行。不过因为我们没有添加内容，所以不会产生实际的文件。

3. 主题

这里有两种方法来更换主题

3.1. 简单配置

下载主题文件到项目中
在文件头部添加配置 #+SETUPFILE: <path to .theme file>, 具体可参考原文

3.2. 高级配置

第一种方法由于是将配置添加在 org 文件顶部，所以只能单行书写，如果要稍微调整样式很困难，所以我们需要更灵活的配置方法

将所需主题的 css 内容全部复制出来，贴到我们之前准备的 org-static/css/stylesheet.css 文件中
在 org 文件中添加样式导入 #+html_head: <link rel="stylesheet" type="text/css" href="css/stylesheet.css" />
完成

3.2.1. 定制样式

直接修改样式源码(org-static/css/stylesheet.css)即可