Org-Site

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

1 Introduction

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

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

2 Installation

2.1 Install libs

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

(dolist (lib '(dash ht s loop with-namespace mustache))
 (el-get-install lib))

Then add the following code to your .emacs: 

(add-to-list 'load-path (expand-file-name
                         "~/.emacs.d/el-get/dash"))
(add-to-list 'load-path (expand-file-name
                         "~/.emacs.d/el-get/ht"))
(add-to-list 'load-path (expand-file-name
                         "~/.emacs.d/el-get/loop"))
(add-to-list 'load-path (expand-file-name
                         "~/.emacs.d/el-get/mustache"))
(add-to-list 'load-path (expand-file-name
                         "~/.emacs.d/el-get/s"))
(add-to-list 'load-path (expand-file-name
                         "~/.emacs.d/el-get/with-namespace"))

2.2 Install org-site

OK, well done, let's install org-site. 

git clone git://github.com/xiaohanyu/org-site.git

Add org-site to your load path 

(add-to-list 'load-path (expand-file-name
                         "/your/path/to/org-site"))

(require 'org-site)

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

3 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.

3.1 Org-site internals

3.1.1 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.

3.1.2 Things about code

org-site is based heavily on org-mode, expecially 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.

4 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. with-namespace.el: interoperable elisp namespaces
  5. dash.el: A modern list library for Emacs. This is required by mustache.el, not by org-site directly.

5 Todo

5.1 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

5.2 Project enhancement

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



comments powered by Disqus