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:
- org sources and html files managed by git
- incremental publication (according to
git diff
command) - tags support (auto generated)
- search engine support (auto generated)
- a much more beautiful theme than the default one
- theme customization support
- commenting (implemented using disqus)
- site visiting tracking (implemented using google analytics)
- index/about page support (auto generated if no default provided)
- highly customizable
- 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
- 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
- org-page does preparation jobs
- 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
- update blog/wiki index pages, tag pages
- publication finished
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
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")
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
. :-)
- Emacs: this is an “of-course” dependency
- org mode (version >= 8.0): in Emacs, “M-x list-packages”, make sure org-mode version >= 8.0. reference
- git: a free and open source version control system
- mustache.el: a mustache templating library for Emacs
- Be sure htmlize.el is installed to make syntax highlighting work
- 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.
For more customization info, please see the Commentary
section in
file org-page.el
and op-vars.el
.