Org-page: Static Site Generator

Introduction

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

Org-page provides following features:

org sources and html files managed by git
incremental publication (according to git diff command)
category support
tags support (auto generated)
RSS support (auto generated)
search engine support (auto generated)
a beautiful theme
theme customization support
commenting (implemented using disqus/duoshuo)
site visiting tracking (implemented using google analytics)
index/about page support (auto generated if no default provided)
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

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
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
org-page does preparation jobs
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
update index page of each category, and tag pages
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

emacs: this is an “of-course” dependency
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
git: a free and open source version control system
mustache.el: a mustache templating library for Emacs
htmlize.el: a library for syntax highlighting (usually this library is shipped with emacs)
dash.el: a modern list library for Emacs
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.

pschmied/org-page