org-site: static site generator based on Emacs Org-mode

Announcement

This project has been stopped as an experimentation to write a static site generator with Emacs Lisp. But still, I’ll keep the code here, just for demo.

I’ve found it’s not convenient to write such a thing with Emacs Lisp since I have to do a lot of hack such as defadvice and with-temp-buffer, etc to match out necessary part from org-mode files.

I’ve switched to Nanoc for my personal website, which is also used by GitHub for its GitHub Developer and GitHub Help.

If you still want a org-mode elisp-based solution, then org-page may be the only choice.

Thanks.

Introduction

Org-site is a static site generator based on Emacs org-mode. http://xiaohanyu.github.io/org-site/ provide a sample GitHub Pages hosted site generated by org-site.

It’s not designed to be a so-called static blog generator, however, org-site will support some simple wiki-like site generation.

Features of org-site:

1. A convenient workflow without leaving Emacs
2. Flexible template and theme design, with a default twitter bootstrap theme
3. Automatic index page generation
4. Commenting using disqus
5. Easily switching between multiple org-site projects

Installation

Install libs

Org-site depends on some extra elisp libraries, to install these dependencies, I recommend you install el-get first, and then evaluate the following elisp code snippet in *scratch* buffer by typing C-j, C-x C-e or M-x eval-print-last-exp:

(let ((el-get-sources))
  (add-to-list 'el-get-sources
               '(:name org-site
                       :type github
                       :depends (mustache)
                       :pkgname "xiaohanyu/org-site"))
  (el-get 'sync (mapcar 'el-get-source-name el-get-sources))
  (require 'org-site))

That’s all, now let’s create our first org-site.

Usage

Org-site provides following shortcut commands to facilitate your workflow:

• org-site-new-project: create a new org-site project.
• org-site-load-project: load an existing org-site project and set it to the current org-site project.
• org-site-new-post: create a new post page.
• org-site-new-wiki: create a new wiki page.
• org-site-publish: publish org-site to html site, other formats like pdf will be supported in future.

The basic workflow is org-site-new-project or org-site-load-project, then org-site-new-post, org-site-new-wiki, and then finally org-site-publish, that’s it.

Org-site internals

The basic directory structure of org-site project

When you org-site-new-project, you will get the following directory structure:

about.org		# about page of your site
index.org		# index page of your site
org-site-config.el	# org-site project config file
post			# post directory
wiki			# wiki directory

In org-site-config.el, you should set your basic information about your site, such as site url, site title, author name and email, disqus url/identifier, etc.

There’re two types of page in org-site, post and wiki. Generally, posts are updated one by one, while wikis are updated little by little. Later version of org-site will add some more flexible feature support and differentiation to these two different pages, but currently org-site treat them different but handle them the same.

Things about code

org-site is based heavily on org-mode, especially on org-publish and org-export-as-*. Internally, org-site do some monkey patching to org-export-as-* to support mustache template rendering, thus provide a flexible theme and customization support.

Tips

Preview your org-site in localhost

If you want to publish your org-site to public, you must set org-site-url to your real site url, see https://github.com/xiaohanyu/org-site/blob/gh-sources/org-site-config.el for a live example.

If you just want to preview your org-site in localhost, you can set org-site-url to “localhost”, then use things like python -m SimpleHTTPServer to provide a simple http localhost site.

Dependencies

1. Emacs: Of course it needs Emacs
2. Org mode: Another of course
3. mustache.el: org-site use mustache as its template render engine.

And mustache.el depends following libs, so:

1. ht.el: The missing hash table utility library for Emacs.
2. loop.el: friendly imperative loop structures for Emacs lisp
3. s.el: The long lost Emacs string manipulation library.
4. dash.el: A modern list library for Emacs. This is required by mustache.el, not by org-site directly.

Todo

Feature enhancement

• Add exportable pdf support
• RSS export
• Customizable TOC(Table of Contents)
• Sidebar?
• Org-mode code weave/tangle to support literate programming
• A copiable, collapsible code block
• Configurable org html source
• Some more theme?
• Site statistics, gravatar, etc.
• Post Category/Tag support
• Math/TeX/MathJax test and support
• Localhost/Production support?
• Search engine support

Project enhancement

• Add an impressive(I hope that) github page generated by org-site itself, yeah.
• Documentation work.
• TDD support based on elisp ERT?