EGO

Static site generator based on Emacs, Git and Org-mode

EGO 使用手册

介绍

EGO 是一个由 org-pageorg-webpage 派生出来的项目,是一个基于 Emacs、git 服务和 org-mode 的一个静态站点生成器。(什么是静态站点生成器?google、bing 或者百度一下)

本项目依据 GPL 许可证(GNU General Public License)发布。

使用方法

安装

可以从 melpa 安装,或者用 git clone 后处理。

设置

下面是 emacs-china 的设置,安装好 EGO 后,将该设置写入配置即可管理 emacs-china。

CAUTION: 直接 clone emacs-china 后,需要 checkout master 和 source 后才能使用 emacs-china,否则会导致意外情况。

;; the following is only needed if you install EGO manually
(add-to-list 'load-path "path/to/EGO")

(require 'ego)

(ego-add-to-alist 'ego-project-config-alist
               `(("emacs-china" ; 站点工程的名字
                 :repository-directory "~/github/emacs-china.github.io" ; 站点的本地目录
                 :site-domain "http://emacs-china.github.io/" ; 站点的网址
                 :site-main-title "EMACS-CHINA" ; 站点的标题
                 :site-sub-title "=============>集思广益" ; 站点的副标题
                 :theme (default) ; 使用的主题
                 :summary (("years" :year :updates 10) ("authors" :authors) ("tags" :tags)) ; 导航栏的设置,有 category 和 summary 两种
                 :source-browse-url ("Github" "https://github.com/emacs-china") ; 你的工程源代码所在的位置
                 :personal-disqus-shortname "emacs-china" ; 使用 disqus 评论功能的话,它的短名称
                 ;; :personal-duoshuo-shortname "emacs-china" ; 使用 多说 评论功能的话,它的短名称(由于多说已经关闭,这里就此废置)
                 :confound-email nil ; 是否保护邮件名称呢?t 是保护,nil 是不保护,默认是保护
                 :ignore-file-name-regexp "readme.org" ; 有些不想发布成 html 的 org 文件(但是又想被导入 git 进行管理),可以用这种正则表达的方式排除
                 :web-server-docroot "~/webRoot/emacs-china.github.io" ; 本地测试的目录
                 :web-server-port 5432); 本地测试的端口

                 ;; 你可以在此添加更多的站点设置
               ))

TIP: 你可以仿照上面来设置自己的站点。

你可以通过以下方式发现 EGO 的设置方法(英文)

C-h v ego-project-config-alist
C-h v ego-config-fallback

新建 Repository

通过以下方式创建新的 Repository(也就是一个新站点了):

M-x ego-new-repository

这种方式只能进行一个初级的设置,要想让它正常工作,还是需要设置 ego-project-config-alist 变量。

新建文章

用以下方式创建新文章:

M-x ego-new-post

测试单独文章的 html 页面

使用以下命令可以生成当前 org 文件所对应的 html 文件,并浏览:

M-x ego-test-current-page

发布

用以下命令生成 html 文件,并按需传送到远程端:

M-x ego-do-publication

这条命令会问你如下几个问题:

  1. Which project do you want to publish?
    ~ 发布哪个站点?
  2. Choose a job from the jobs below:
    ~ "1. Test partial publish"
    ~ "2. Partial publish"
    ~ "3. Test full publish"
    ~ "4. Full publish"
    ~ 从以下四个选项里选择一种发布方式:
    ~ "1. 增量发布测试"
    ~ "2. 增量发布"
    ~ "3. 完全发布测试"
    ~ "4. 完全发布"
    ~ 测试即意味着发布到 web-server-docroot 文件夹下用 emacs 自带的 web server 查看,是本地的并不传送到远端。
  3. (when (2) is partial) Base git commit: HEAD~1 ?
    ~ 将哪些提交视为改变文件?(当第三项选了带了 “partial” 字符串时出现的选项,不懂得话回车即可)
  4. Input checkin messages. (The message won't be inputted if you have checkined before.)
    ~ 输入 checkin 信息,了解 git 的话应该知道
  5. (when (2) is not "test") There will be some questions for "publish-config"
    ~ 对发布到远端的设置进行具体询问(在第二项没有 “test” 字符串时出现)

注意: 当进行没测试过的发布时,任何未经测试的内容变化都不会被发布。也即,任何内容变化在真正发布之前必须经过测试发布。

你可以在 message buffer 和 EGO OUTPUT buffer 里跟踪整个过程。

异步发布

你可以使用 async.el 包来包裹 ego-do-publication 命令,使得该命令异步执行。

关于 async.el 包的用法可以参看这里(英文) : Async.

这里是一个例子: (你当然不能直接使用它,但是可以参考它进行自己的设置,就当是一个使用 async 的作业吧)

(require 'ego)
(require 'async)
(defun ego-async-do-publish (&optional project-name
                                       test-and-not-publish
                                       force-all
                                       base-git-commit
                                       checkin-all
                                       publish-config)
  (interactive
   (let* ((j (or ego--default-project-name
                 (completing-read "Which project do you want to publish? "
                                  (delete-dups
                                   (mapcar 'car ego-project-config-alist))
                                  nil t nil nil ego--last-project-name)))
          (p (y-or-n-p "Action:  [Yes] Test, [No] Tested Publish. "))
          (f (y-or-n-p (format "Publish all org files of \"%s\" project? " j)))
          (b (unless f (read-string "Base git commit: " "HEAD~1")))
          (c (read-string "checkin message (won't show in 'git log' if you have committed all): "))
          (a nil))
     (list j p f b c a)))
  ;; set ego remote push (publish-config)
  (unless test-and-not-publish
    (setq ego--current-project-name project-name)
    (setq ego--last-project-name project-name)
    (setq publish-config
          (ego--git-get-publish-config (ego--get-repository-directory)
                                      (ego--get-config-option :repository-org-branch)
                                      (ego--get-config-option :repository-html-branch))))

  (message "See *EGO OUTPUT* buffer and *emacs* buffer for information")
  (async-start
   `(lambda ()
      ;; load packages and set load-path
      (setq package-user-dir ,(expand-file-name "~/.emacs.d/elpa/"))
      (package-initialize)
      (add-to-list 'load-path ,(expand-file-name "~/github/org-mode/lisp"))
      (add-to-list 'load-path ,(expand-file-name "~/github/org-mode/contrib/lisp" t))
      (add-to-list 'load-path ,ego-load-directory)

      ;;set color-theme
      (add-to-list 'load-path ,(expand-file-name "~/.emacs.d/color-theme-6.6.0"))
      (require 'color-theme-autoloads "color-theme-autoloads")
      (color-theme-initialize)
      (color-theme-dark-blue2)

      ;; set coding-system
      (set-terminal-coding-system 'utf-8-unix)
      (set-keyboard-coding-system 'utf-8-unix)
      (prefer-coding-system 'utf-8-unix)
      (setq save-buffer-coding-system 'utf-8-unix
            coding-system-for-write 'utf-8-unix)

      ;; pre-set ego configurations
      (require 'cl-lib)
      (require 'ego)
      (setq ego-project-config-alist ',ego-project-config-alist)

      ;; Make EGO show svg images
      (require 'ox-html)
      (defun kd/org-html--format-image (source attributes info)
        "Return \"img\" tag with given SOURCE and ATTRIBUTES.
  SOURCE is a string specifying the location of the image.
  ATTRIBUTES is a plist, as returned by
  `org-export-read-attribute'.  INFO is a plist used as
  a communication channel."
        (org-html-close-tag
         "img"
         (org-html--make-attribute-string
          (org-combine-plists
           (list :src source
                 :alt (if (string-match-p "^ltxpng/" source)
                          (org-html-encode-plain-text
                           (org-find-text-property-in-string 'org-latex-src source))
                        (file-name-nondirectory source)))
           attributes))
         info))
      (advice-add 'org-html--format-image :override #'kd/org-html--format-image)

      ;; without org-to-html if possible
      (unless ,test-and-not-publish
        (if ,base-git-commit
            (setq ego--publish-without-org-to-html 1)
          (setq ego--publish-without-org-to-html 2)))

      ;; ego-do-publication here
      (ego-do-publication ,project-name
                          ,test-and-not-publish
                          ,force-all
                          ,base-git-commit
                          ,checkin-all
                          ',publish-config)

      ;; waiting for push remote success or just wait http-server in which case you have to close *emacs* buffer manually
      (while (not ego--async-publish-success)
        (sit-for 1))

      ;; return the result
      (with-current-buffer (get-buffer-create ,ego--temp-buffer-name)
        (buffer-string))
      )
   `(lambda (result)
      (with-current-buffer (get-buffer-create ego--temp-buffer-name)
        (insert (format "*EGO output* should be :\n %s \nego-async-do-publish done!" result))))))

你可以在 emacs buffer 和 EGO OUTPUT buffer 里跟踪整个过程。

注意事项

EGO 只支持 emacs 24.5 及以后的版本。

在我最新编译的 emacs-25 里,发现如果用 dired 打开了 repository 里面一些目录,这时 EGO 自带的 git change branch 无法正确地切换 branch。造成 repository 里文件混乱。

解决办法:关闭那些被打开的 repository 内部目录的 buffer。(repository 这个目录倒是没什么关系。)

一些特点

EGO 还支持 “主题继承”,能让多站点管理时的主题修改轻松很多。这里只点一下要点:

:theme (haru emacs_love)

haru 是在 emacs_love 上修改的主题。实际上 :theme 对应的括号里可以有很多主题,形成一个主题链(越开头越优先)。

一些缺点

假若要删除发布后的 html 文件,只能用 git 跳转到 html 所在分支,进行手动删除后,将该分支提交到服务器端。

也即是说,删除发布后的 html 文件比较麻烦。(使用传统的 git 操作模式)

FAQ

为什么没有发布那些包含中文的 org 文件?

请在 repo 目录下手工执行 git ls-tree -r --name-only HEAD, 若发现所有的中文都显示成乱码,那么请执行

git config --global core.quotepath false

之后,再重新发布。

待完成事项

目前只有一个 default 主题,试试看能否公开招募到新主题,然后维护一个主题的超链接列表。

如有问题请移步 Issues 提问