Org-page: Static Site Generator

Introduction

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

Org-page provides the 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/hashover)
10. Website traffic analytics (implemented using google analytics)
11. Index/about page support (auto generated if no default is provided)
12. Site preview
13. 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 an example.

Workflow

1. Specify a git repo where the org source files will be on the “source” branch and the generated html files will be on the “master” branch (the branch names can be customized). Repos may be created manually or by org-page’s op/new-repository command.
2. Specify a “base commit” (the most recent prior 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 then be marked for publication.
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 of these kinds of changes but since deletion does not happen often, org-page has not implemented it yet
5. Update the index page for each category and tag.
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 the “doc” folder.

Installation

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

Configuration

Add the following lines to 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, duoshuo or hashover
(setq op/personal-disqus-shortname "your_disqus_shortname")
(setq op/personal-duoshuo-shortname "your_duoshuo_shortname")
(setq op/hashover-comments t)
;;; the configuration below are optional
(setq op/personal-google-analytics-id "your_google_analytics_id")

Publication

Evaluate the following code to publish your changes:

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

or just

(op/do-publication)

You can also run it interactively: M-x op/do-publication <Enter>

NOTE: Org-page does NOT commit your org files to git, so you have to commit them manually before you run this command.

Site preview in browser

Just run M-x op/do-publication-and-preview-site <Enter>, the site will be published in ~/.op-tmp, then it will be previewed in browser automatically.

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
8. simple-httpd: A simple Emacs web server is required for site preview
9. git.el: An Elisp API for programmatically using Git

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 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, org-page 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.