Skip to content

xiaohanyu/org-site

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
doc
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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?

About

[Stopped] A static site generator based on Emacs Org-mode.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published