emacs-china / Ego

#+TITLE: README of EGO #+AUTHOR: Feng Shu, Kuangdash #+EMAIL: [email protected] #+DATE: 2015-07-02

[[https://melpa.org/#/ego][file:https://melpa.org/packages/ego-badge.svg]]

*中文用户可以点击 [[https://emacs-china.github.io/EGO][EGO 中文手册]] ~*

• Introduction

EGO is a static site generator that depends on [[http://www.gnu.org/software/emacs][Emacs]], [[http://git-scm.com][Git]] and [[http://orgmode.org/][Org-mode]]. it originates from Feng Shu's [[https://github.com/tumashu/org-webpage][org-webpage]], which is a fork of Kelvin H's [[https://github.com/kelvinh/org-page][org-page]].

EGO provides features below:

1. Org sources and html files managed by git
2. Incremental publication (according to =git diff= command)
3. Category support (not recommended)
4. Tags support (auto generated)
5. RSS support (auto generated)
6. Search engine support (auto generated)
7. A beautiful theme
8. Theme customization support is well (using mustache template)
9. Commenting (implemented using disqus/duoshuo)
10. Website traffic analytics (implemented using google analytics)
11. Index/about page support (auto generated if no default is provided)
12. Include a tiny emacs web server, which can be used to test publish.
13. Manage multi-site configs in an emacs session easily.

"Emacs-version >= 24.5" is required.

• Usage

** Installation Use package repo [[http://melpa.milkbox.net/][melpa]]. or =git clone= it manually.

** Configuration The follow code is [[http://emacs-china.github.io][emacs-china]] 's config , you can paste and adjust it to your =.emacs= file:

#+BEGIN_SRC emacs-lisp ;; 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" :repository-org-branch "master" ; 源文件所在 branch :repository-html-branch "master" ; html 文件所在 branch :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)) :source-browse-url ("Github" "https://github.com/emacs-china") :personal-disqus-shortname "emacs-china" ;; :personal-duoshuo-shortname "emacs-china" ; deprecated because of duoshuo inexistence :confound-email nil :ignore-file-name-regexp "readme.org" :web-server-docroot "/webRoot/emacs-china.github.io" :web-server-port 5432)

               ;; more projects or sites config can be added here

               ))

#+END_SRC

You can find more config options and theirs default values by commands:

#+BEGIN_EXAMPLE C-h v ego-project-config-alist C-h v ego-config-fallback #+END_EXAMPLE

** Create New Repository Using the following command to create a new repository:

#+BEGIN_EXAMPLE M-x ego-new-repository #+END_EXAMPLE

The repository is preliminary, you have to configure the =ego-project-config-alist= to make it work!

** Create New Post Using the following command to create a new post:

#+BEGIN_EXAMPLE M-x ego-new-post #+END_EXAMPLE

** Test Post Using the following command to test current opening org-file: #+BEGIN_EXAMPLE M-x ego-test-current-page #+END_EXAMPLE

You can see the html version of the org-file in browser.

** Publication The simplest way is run:

#+BEGIN_EXAMPLE M-x ego-do-publication #+END_EXAMPLE

This command will ask you some questions:

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"
3. (when (2) is partial) Base git commit: HEAD~1 ?
4. Input checkin messages. (The message won't be inputted if you have checkined before.)
5. (when (2) is not "test") There will be some questions for "publish-config"

CAUTION: When untested publication, anything modified won't be published.If you want modified contents to be published, just test it before publication.

you can track the process in message buffer and EGO OUTPUT buffer.

** Async Publication You can use =async.el= package to wrap the command =ego-do-publication= in order to publish the static site without a wait.

You can find some example about how to use =async.el= package here : [[https://github.com/jwiegley/emacs-async][Async]].

And here is an example: (There are some important points so that you had better see it.)

#+BEGIN_SRC emacs-lisp (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))))))

#+END_SRC

you can track the process in emacs buffer and EGO OUTPUT buffer.

• Dependencies

1. [[http://www.gnu.org/software/emacs/][emacs]]: this is an "of-course" dependency, "version >= 24.5" is required.
2. [[http://orgmode.org/][org mode]]: v8.0 is required, please use =M-x org-version = to make sure you org mode version is not less than 8.0
3. [[http://git-scm.com][git]]: a free and open source version control system
4. [[https://github.com/Wilfred/mustache.el][mustache.el]]: a mustache templating library for Emacs
5. [[http://fly.srk.fer.hr/~hniksic/emacs/htmlize.el.cgi][htmlize.el]]: a library for syntax highlighting (usually this library is shipped with emacs)
6. [[https://github.com/magnars/dash.el][dash.el]]: a modern list library for Emacs
7. [[https://github.com/Wilfred/ht.el][ht.el]]: a modern hash-table library for Emacs
8. [[https://github.com/skeeto/emacs-web-server][simple-httpd]]: a web server library in Emacs for test

• Known issues

• CAUTION when there are opened directories in the repository (which don't contain the repository itself), =ego--git-change-branch= will mess up the files in the repository. So, close all opened directories in the repository before =ego-do-publication= .
• Currently the deletion change handler has not been implemented so if you deleted some org sources, you may have to manually delete corresponding generated html files.
• URI path change detection is not available. That is, if you make a post with the URI "/blog/2013/03/25/the-old-post-name" and then change this value in your org source, EGO would be unable to detect that this has happened. it will only publish a new html file for you so you need to delete the old html file related to the old URI manually.

• Roadmap [2/3]

• [X] Next/Previous Page links

  Use =M-x org-insert-link= (Normal key binding is =C-c C-l=) and choose =ego-link:= to insert a link to an org file. The link will be exported as hyperlink to the correct html page.

  The function can be applied to the condition of Next/Previous Page links -- Get a chain of files in a logical order rather than just a time sequence.

  When reply "Is it a PERVOUS(bi-directional) link? " with "y" (according to the =M-x org-insert-link ego-link:= process), you can add the bi-directional link.

  The link is assigned to class "ego_link" with label "span", you can customize it in CSS.

• [ ] More themes

  Just maintain a list of hyperlinks to the other themes except the default.

  Now considering using 'ego-map.el' which wipes off the restriction of EGO theme customization. But what's the shape it should be?

• [X] upload to melpa

• FAQ ** Why can't I publish those org files containning chinese charactors? Execute src_sh{git ls-tree -r --name-only HEAD} in the repo directory, if the chinese charactor displays like a mass, please execute #+BEGIN_SRC sh git config --global core.quotepath false #+END_SRC and then try again.