使用org-mode和ox-hugo写博客

本文

主要介绍如何使用org-mode和ox-hugo写博客。

版本 说明
0.1 初版发布

背景

  • 主机: Thinkpad S2
  • 系统: Deepin GNU/Linux 15.11
  • 内核: Debian 6.3.0-18+deb9u1
  • hugo版本: hugo 0.58
  • emacs版本:Linux GNU Emacs 26.3

参考

声明

当你看到此帖子,我必须要声明一下,如果你是非emacs用户,并不强烈推荐你使用emacs org-mode来写博客,除非你有足够的兴趣了解和学习emacs。

什么是org-mode?什么是ox-hugo?

  • org-mode是文本编辑软件Emacs的一种支持内容分级显示的编辑模式,是一个基于快速高效的文本方式来实现做笔记、管理待办事项(TODO list)以及做项目计划的模式。本人使用感受最好的就是大纲显示模式。
  • ox-hugo是emacs的一个插件,可以将org格式文件转换为hugo识别的markdown格式文件。

安装emacs和安装ox-hugo插件

安装emacs就不介绍了,可参考我的另一篇帖子 emacs的安装

这里主要介绍一下如何安装ox-hugo插件。给emacs安装插件可以使用emacs的包管理器,首先添加以下代码到.emacs中(或.emacs.d/init.el),然后 “M-x package-list-packages” (初学者可能不知道什么意思,那你就需要了解了解emacs了, M就是Alt键,打开emacs,敲击组合键 Alt+x ,启动命令窗口,然后输入命令“package-list-packages”(tab键可以补全)),接下来你会看到所有插件的列表,找到“ox-hugo”,可以点击,然后根据提示下载安装,也可以使用快捷键操作,如下:

  • i : 选择要安装的包
  • d : 选择要删除的包
  • U : 升级已安装的包
  • x : 执行操作
  • d : 选择要删除的包
1
2
3
4
5
6
(require 'package)
(add-to-list 'package-archives
             '("melpa" . "http://melpa.milkbox.net/packages/") t)
(package-initialize)

;;如果不行,可能是访问国外网络问题,可将其替换为国内镜像源 http://elpa.zilongshanren.com/melpa/

emacs的基础使用

emacs的使用可以简单了解一下emacs启动页面的使用手册,简单了解就可以上手了。这里把最基础的使用粘贴出来。

Emacs的快捷键都是绑定在ctrl和alt上的,例如C-x就是ctrl+x,M-x就是alt+x。

  • 文件操作
    • C-x C-f 打开文件
    • C-x C-s 保存文件
    • C-x C-c 退出Emacs
  • 编辑操作
    • C-f 前进一个字符(方向键也可以)
    • C-b 后退一个字符(方向键也可以)
    • C-a 移到行首
    • C-e 移到行尾
    • C-p 后退一行(方向键也可以)
    • C-n 前进一行(方向键也可以)
    • M-g M-g 跳到指定行
    • M-< 文档头部(配合Shift键)
    • M-> 文档尾部(配合Shift键)
    • C-d 删除一个字符(delete键也可以)
    • C-k 删除一行
    • C-Shift-空格 标记开始区域
    • C-w 删除标记区域
    • C-y 粘贴删除的内容,注意:C-y可以粘贴连续C-k删除的内容;先按C-y,然后按M-y可以选择粘贴被删除的内容
    • M-w 复制标记区域
    • C-/ or C-x u 撤消操作
  • 窗口操作
    • C-x 0 关闭本窗口
    • C-x 1 只留下一个窗口
    • C-x 2 垂直均分窗口
    • C-x 3 水平均分窗口
    • C-x o 切换到别的窗口
    • C-x s 保存所有窗口的缓冲
    • C-x b 选择当前窗口的缓冲区
  • 缓冲区列表操作
    • C-x C-b 打开缓冲区列表
    • C-x k 关闭缓冲区
  • 搜索模式
    • C-s 向前搜索
    • C-s 查找下一个
    • ENTER 停止搜索
    • C-r 反向搜索
    • C-s C-w 以光标所在位置的字为关键字搜索
    • M-% (配合Shift键) 替换, 输入y表示同意此处替换,否则输入n,全部替换使用!
  • 帮助
    • C-h t 入门指南
    • C-h ? 查看帮助列表

org-mode和ox-hugo写博客

ox-hugo 支持两种方式来管理 org 格式的博客文章,一种是多个文章放在同一个 org 文件里,另一种是对不同的文章使用独立的 org 文件。本人喜欢第一种方式,我会将同一类的博客文章放在同一个org文件来管理。如下:

emacs org mode

文件头部说明

  • HUGO_BASE_DIR:这里是博客的根目录,因为我的org文件放在博客根目录下的 orgposts ,所以这里博客的根目录就是 “../” ,也就是本目录的上一层目录
  • HUGO_SECTION:生成的markdown文件的位置,比如 “./post/create_blog_site/” 就会将markdown文件生成在博客根目录下的 “content/post/create_blog_site/”
  • hugo_auto_set_lastmod:最后修改的时间,也就是org转markdown时的时间,t的话会自动生成,也可以选择f,这个时间在jane主题也就是文章末的最后更新时间
  • hugo_custom_front_matter:这里是markdown文件头部参数的设置,比如toc,是否开启目录,不开启的话浏览时无目录显示,为了阅读方便建议开启
  • hugo_categories:分类名称,我是将同一类博客放在了一个org文件,这里就是分类名,然后每个subtree就是一个博客,会生成一个markdown文件
  • author:nil:这里是作者名称,在hugo的配置文件中已经配置了作者名称,这里将作者名称的控制关掉
1
2
3
4
5
6
7
#+HUGO_BASE_DIR: ../
#+HUGO_SECTION: ./post/create_blog_site/
#+hugo_auto_set_lastmod: t
#+hugo_custom_front_matter: :toc true
#+hugo_categories: 搭建博客站点

#+OPTIONS: author:nil

subtree

下面是一个subtree的内容(为了防止转义,前面都加了#号,实际中无#号),下面一行一行介绍:

  • 第一行是一级标题,这里也就是一个subtree,也是文章标题,后面冒号间的文字是标签,对应markdown文件中的tag,注意,冒号需要为英文符号,也可以使用 C-c C-c 快捷键输入tag;标题前的 DONE 表示完成状态,除此之外还有 TODO 状态,对应markdown文件中的 draftTODO 状态时,会认为是草稿,不会发布到站点,还要注意的是,状态不是手动敲上去的,而是光标放在标题行,通过Shift和左右键切换
  • 第二行是文章创建的时间,对应markdown文件的date
  • 第三四五行,EXPORT_FILE_NAME是输出markdown文件的名称,这里是subtree的属性描述,可使用参数应该还有很多,不过暂时没了解
  • 最后就是博客内容了,二级标题和三级标题
1
2
3
4
5
6
7
#* DONE title_level1                               :hugo:emacs:
# CLOSED: <2019-09-13 五 14:22>
#   :PROPERTIES:
#   :EXPORT_FILE_NAME: Thinkpad_S2
#   :END:
#** title_level2
#*** title_level3

特殊需求

  • 外链:可以使用 C-c C-l (这里是小写L)快捷键,输入链接和链接说明
  • 图片:官方提供的方式如下(这里为了防止转义使用的小括号,实际为英文大括号):
1
((< figure src="/image/cook/image0.jpg" title="图片" >))

由于我还是希望对图片显示大小和位置能够控制,也许有其他方法还不知道,不过在这里写一个html格式的图片引用,能够实现我想要的效果,方式如下:

1
2
3
4
<center>
<img width="800" src="/image/me.jpg">
<div style="color:black;"> <b> github新建仓库 </b>  </div>
</center>
  • subtree中设置分类,如下,@后是分类,:后是标签(为了防止转义,添加了#号,实际中无#号)
1
# :@笔记:昨天:今天:明天:
  • 脚注:在需要插入脚注的地方写下 “【fn:1】” ,在文章末尾添加脚注的说明 “【fn:1】 脚注说明” ,这里为了防止转义使用了中文符号,实际中记得使用英文符号

org文件转为markdown文件

  • 将所有subtree都转为对应的Hugo markdown文件,快捷键 C-c C-e H A ,其中 C-c C-e 是导出快捷键,可选的有很多,比如h代表html,l代表laTex等,H代表Hugo,后面的A代表All(快捷键操作过程中会有提示,详细信息可以看提示信息)
  • 将某subtree转为对应的Hugo markdown文件,首先光标移至对应的subtree,再通过快捷键 C-c C-e H H ,其中 C-c C-e 是导出快捷键,H代表Hugo,后面的H代表subtree(快捷键操作过程中会有提示,详细信息可以看提示信息)
  • 其他说明:content不存在对应的目录也没关系,ox-hugo会自动创建

文章原创,可能存在部分错误,欢迎指正,联系邮箱 cao_arvin@163.com。