EGO 使用手册
目录
介绍
EGO 是一个由 org-page 和 org-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
这条命令会问你如下几个问题:
- Which project do you want to publish?
~ 发布哪个站点? - 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 查看,是本地的并不传送到远端。 - (when (2) is partial) Base git commit: HEAD~1 ?
~ 将哪些提交视为改变文件?(当第三项选了带了 “partial” 字符串时出现的选项,不懂得话回车即可) - Input checkin messages. (The message won't be inputted if you have checkined before.)
~ 输入 checkin 信息,了解 git 的话应该知道 - (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 提问