README.org

2022-12-23

Archive for no using ox-hugo anymore. Now I use an fork of org-static-blog, written with pure Elisp.

Org Hugo Lazy

Org hugo lazy (ohl) is an Emacs tool to publish org files to GitHub Page as blog by using Hugo and ox-hugo.

Installation

Needed: Emacs >= 28.2, Org Mode >= 9.5.5

1.Install Hugo Please go to https://gohugo.io/getting-started/installing/ to install Hugo according to your system.

2.Install ox-hugo M-x packag-install RET ox-hugo

3.Install f.el and s.el They are fantastic Emacs API. M-x packag-install RET f, M-x packag-install RET s.

4.CLone or download this tool. Add it to your init.el

(add-to-list 'load-path "<where ohl is>")
(require 'ohl)

Since packages are lazy-loaded, don’t worry about being slow down by ohl

5.(Unnecessary) Since my blog uses Gitalk as comment system, so I add this process to ohl Install GitHug CLI to add new issue automatically. Don’t forget to authorize the device

gh auth login

sudo pacman -S github-cli

Usage

ohl configuration

 (require 'ohl)

 ;; Where to save the cache data
 ;; Default: ~/.emacs.d/ohl
 ;; (setq ohl-db-dir (f-expand "ohl" user-data-directory))

 (setq ohl-project-plist
	;; This is a project
	'(("blog"
	   :base-directory "~/org/blog/"
	   :source-directory "~/org/posts/"
	   :repository-directory "~/org/"
	   :static-relative-directory "assets"
	   :gitalk t
	   :url "https://example.github.io/"
	   :paried-shortcodes "mermaid admonition"
	   :auto-lastmod t
	   :with-toc nil
	   )
	;; This is another project
	  ;; ("emacs"
	  ;;  ...
	  ;;  )
	  ))

• :base-directory: directory of Hugo project.
• :source-directory: where your org files locate
• :repository-directory: your GitHub repo in locality.
• (optional) :static-relative-directory: the relative path of static files to /. Suppose it is set to be assets as above, and there is a image named some.png, then it will be copied into <your hugo project>/static/assets/some.png when exporting. Default
• (optional) :gitalk: if it is t, then ohl will try to add a new issue to your GitHub Page as a comment system of your blog. Default is nil.
• (optional) :url: url of your blog. But it is necessary if ~:gitalk~ is ~t~. No default
• :paried-shortcodes: Allowed custom Hugo Shortcodes, each of them are seperated by space " ". Default is “mermaid admonition”.
• :auto-lastmode: If automatically update the last-modification date. Default is t.
• :with-toc: If posts are exported with table of content. Default is nil (since my Hugo Theme will handle toc).

ohl APIs

ohl-load

Since loading ox package may cost a lot of startup time, I set them to be lazy-loaded, i.e., they load when ohl-load is called. You don’t have to call it manually, other APIs will do implicitly.

Besides, this will override:

• begin_center: from:

   <style>
  	.org-center{
  	margin-left: auto;
  	margin-right: auto;
  	text-align: center;
  	}</style>
   <div class="org-center">
  	content here.
   </div>
      

  to:

   <div class="org-center">
  	content here.
   </div>
      

  i.e., I remove the <script>

• add a hook eh-org-clean-space-for-md after paragraph exported, which wipes the whitespace before and after the blod format wrapping Chinese words.

ohl-generate

To transform all the org files in ohl-source-dir to md recursively. It will check the last modified date of files, then skip the unmodified file – by comparing with data in cache.

Firstly, it will try to load packages by ohl-load.

ohl-generate accpet a parameter plist which is the project of ohl-project-plist. And it trys to add new issues to GitHub Repo. Note that it will not do things about GitHub isseue even :gitalk is t when interactively.

With ohl-auto-gitalk as t, if ohl-generate is called interactively, then it only transform files, not handling Github Issue. Otherwise, it will try to create new issue for each org file since Gitalk use issues as comment system of blog.

ohl-publish

ohl-publish do a little more than ohl-generate: accepted a project, it calls ohl-generate, publishes the site by CLI hugo, and git commit the files to GitHub Repo.

ohl-publish-all

It will try to publish all the projects in ohl-project-plist.

How it works

Here is the design of ohl. Suppose that ohl-auto-gitalk is t.

Firstly it will get issue list of GitHub repo by gh issue list, and extract out all the issue with label Gitalk.

Scan each file in ohl-source-dir, calling function in ox-hugo – org-hugo-export-wim-to-md to transform current org file to md. Meanwhile, it will calculate the MD5 of the string, the relative path of output md file to <your hugo project dir>/content. The MD5 is the unique ID, so that each post in blog can match the correct GitHub Issue.

The explanation of relative path. Assume your Hugo project directory is blog, and your output md locates in blog/content.

blog/content/about.md => about.md
blog/content/posts/just-a-post.md => posts/just-a-posts.md

Try to create a new label by gh label create [md5 of relative path], then try to create a new issue by gh issue create --title [post's title] --body [post's url in your blog] --label "Gitalk,[md5 of relative path]". If network errors occur, they may work improperly.

Call hugo to publish md file to html.

Try to git add/commit/push files to GitHub.