altkatz / org-page

a static site generator based on Emacs and org mode

org-page: static page generator

Introduction

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

*Here is a demo 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, please take the demo and source as example.*

*The how-to document of org-page is incomplete, but as currently there is few user of org-page, maybe only one - me :-(, so I don’t think there is big need to complete it. If you are using org-page, and you cannot make it work after you have had a look at the example mentioned above, you are welcome to drop me a mail, I will help you as I could. :-)*

From v0.3, org-page is not just an enhancement for org publish process, since org publish process is designed for general publication, it is not only for html generation. But what we need, is only html generation with highly customized configuration.

Org-page provides following features:

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

Workflow

1. you specify a git repo, where org sources on its “source” branch (the branch name can be customized, the same below), and generated html files 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 currently deletion is not implemented
   • org-page will separate all sources into two categories: “blog” and “wiki”, a file belongs to which category depends on its folder name, if it is under folder named “blog”, then it is considered as a blog post, so does wiki, files under folders with other names will be considered as blog posts
   • the uri path of generated html depends on #+URI option in org file
5. update blog/wiki index pages, tag pages
6. publication finished

Usage

installation

Org-page depends on mustache.el, so make sure you installed it before you install org-page. (the recommended way is to install it trhough emacs’ package management system)

After you installed mustache.el, clone the repo from github:

git clone http://github.com/kelvinh/org-page.git

configuration

add following lines into your .emacs file:

(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/")
(setq op/personal-disqus-shortname "your_disqus_shortname")
;;; the three configurations below are optional
(setq op/personal-google-analytics-id "your_google_analytics_id")
(setq op/repository-org-branch "your_org_branch_name")
(setq op/repository-html-branch "your_html_branch_name")

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>

For the usage of the variables and function above, please see their documentation, please make good use of your C-h f and C-h v. :-)

Dependencies

1. Emacs: this is an “of-course” dependency
2. org mode (version >= 8.0): in Emacs, “M-x list-packages”, make sure org-mode version >= 8.0. reference
3. git: a free and open source version control system
4. mustache.el: a mustache templating library for Emacs
5. Be sure htmlize.el is installed to make syntax highlighting work

Known issues

• Currently the RSS feature has not been implemented, so the RSS link is unavailable.
• 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.

Additional information

For more customization info, please see the Commentary section in file org-page.el and op-vars.el.