Org-page: Static Site Generator

Introduction

Org-page is a static site generator based on org-mode.

Org-page provides following features:

1. org sources and html files managed by git
2. incremental publication (according to git diff command)
3. category support
4. tags support (auto generated)
5. RSS support (auto generated)
6. search engine support (auto generated)
7. a beautiful theme
8. theme customization support
9. commenting (implemented using disqus/duoshuo)
10. site visiting tracking (implemented using google analytics)
11. index/about page support (auto generated if no default provided)
12. highly customizable

Here is my personal site generated by org-page. The html files and org source files are located at https://github.com/kelvinh/kelvinh.github.com, if you want to give org-page a try, you could take them as example.

Workflow

1. specify a git repo (may created by yourself manually or by org-page’s op/new-repository command), where org sources on its “source” branch (the branch name can be customized, the same below), and generated html files will be on its “master” branch
2. you specify a “base commit” (previouse commit will be used if omitted), org-page will read changes between the latest commit and the specified base commit on branch “source”, the changes will be published
3. org-page does preparation jobs
4. publish the changes read in step 2, a change can be an addition, a modification, or a deletion, org-page is designed to handle all these kinds of changes, but since deletion does not often happen, so org-page has not implemented it yet
5. update index page of each category, and tag pages
6. publication finished

Usage

Here is a general introduction about how to use org-page, for more detailed introduction and configuration, please see “quick-guide.org” in “doc” folder.

installation

Org-page is now available in the famous emacs package repo melpa, so the recommended way is to install it trhough emacs’ package management system, for more info about installation, please see quick-guide.org in “doc” folder.

configuration

add following lines into your .emacs file:

;;; the following is only needed if you install org-page manually
(add-to-list 'load-path "path/to/org-page")
(require 'org-page)
(setq op/repository-directory "path/to/your/org/repository")
(setq op/site-domain "http://your.personal.site.com/")
;;; for commenting, you can choose either disqus or duoshuo
(setq op/personal-disqus-shortname "your_disqus_shortname")
(setq op/personal-duoshuo-shortname "your_duoshuo_shortname")
;;; the configuration below are optional
(setq op/personal-google-analytics-id "your_google_analytics_id")

publication

evaluate following code to do publication:

(op/do-publication nil "HEAD^1" "~/org-pub/" nil)

or just

(op/do-publication)

and, you could run it interactively: M-x op/do-publication <Enter>

Dependencies

1. emacs: this is an “of-course” dependency
2. org mode: v8.0 is required, please use M-x org-version <RET> to make sure you org mode version is not less than 8.0
3. git: a free and open source version control system
4. mustache.el: a mustache templating library for Emacs
5. htmlize.el: a library for syntax highlighting (usually this library is shipped with emacs)
6. dash.el: a modern list library for Emacs
7. ht.el: a modern hash-table library for Emacs

Known issues

• Currently the deletion change handler has not been implemented, so if you deleted some org sources, you may have to manually delete corresponding html files generated.
• URI path change detection is not available, that is, if you make a post with URI “/blog/2013/03/25/the-old-post-name”, then you changed it in your org source (with new value of #+URI property), org-page is unable to detect this kind of change, 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.