#+TITLE:     Org-page: Static Site Generator
#+AUTHOR:    Kelvin Hu
#+EMAIL:     ini.kelvin@gmail.com
#+DATE:      2012-08-23


* Introduction

  Org-page is a static site generator based on [[http://orgmode.org/][org-mode]].

  Org-page provides 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)
  10) site visiting tracking (implemented using google analytics)
  11) index/about page support (auto generated if no default provided)
  12) highly customizable

  *[[http://kelvinh.github.com][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

   1. 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
   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 since deletion does not often happen, so org-page has not implemented it yet*
   5. update index page of each category, and tag pages
   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 "doc" folder.*

** installation

   Org-page is now available in the famous emacs package repo [[http://melpa.milkbox.net/][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

  1. [[http://www.gnu.org/software/emacs/][emacs]]: this is an "of-course" dependency
  2. [[http://orgmode.org/][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. [[http://git-scm.com][git]]: a free and open source version control system
  4. [[https://github.com/Wilfred/mustache.el][mustache.el]]: a mustache templating library for Emacs
  5. [[http://fly.srk.fer.hr/~hniksic/emacs/htmlize.el.cgi][htmlize.el]]: a library for syntax highlighting (usually this library is shipped with emacs)
  6. [[https://github.com/magnars/dash.el][dash.el]]: a modern list library for Emacs
  7. [[https://github.com/Wilfred/ht.el][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.