plumpmath / org-webpage

A static site generator based on org-mode

• org-webpage README
  • Installation
  • Configuration
  • Publication
  • Dependencies
  • Known issues

org-webpage README

org-webpage is a static site generator based on org-mode, which code derived from Kelvin H's org-page.

The main differents of two projects are as follow:

1. org-webpage's core don't hard code git, its process is like below:

   [ Org files in repository]  [ Website project configure ]
   
                |                           |
           < Export >                 < Generate >
                |                           |
   
          [ HTML files ]               [ Uploader ]  <- ( Uploader is a bash script )
   
                |                           |
                |                           |
                +-------------+-------------+
                              |
                              |
                      < Run Uploader >  <- ( For example: git uploader, rclone uploader or others )
                              |
                              |
   
                          [ REMOTE ]
   

2. org-webpage's default config is `org-publish-project-alist' style alist, which can manage multi-site configs in an emacs session easily.

3. org-website find theme-files from a themes-list in sequence and same theme-file first found will be used. User can set fallback theme with the help of this feature.

4. org-website include a tiny emacs web server, which can be used to test publish.

5. org-website can use other uploaders to upload website, for example: rclone.

6. …

Installation

org-webpage is now available from the famous emacs package repo melpa so the recommended way is to install it through emacs package management system. For more info about installation, please see tips.org in the "doc" folder.

Configuration

org-webpage use variable `owp/project-config-alist' to store all projects's configures, user can add a project with the help of `add-to-list' function, but the easiest way is using `owp/add-project-config' function.

The follow code is my website's config, you can adjust and paste it to your .emacs file:

(add-to-list 'load-path "path/to/org-webpage") ; Only needed if you install org-webpage manually

(require 'org-webpage)

(owp/add-project-config
 '("tumashu.github.com"
   :repository-directory "~/project/emacs-packages/tumashu.github.com"
   :remote (git "https://github.com/tumashu/tumashu.github.com.git" "master")
   ;; you can use `rclone` with `:remote (rclone "remote-name" "/remote/path/location")` instead.
   :site-domain "http://tumashu.github.com/"
   :site-main-title "Tumashu 的个人小站"
   :site-sub-title "(九天十地，太上忘情！！！)"
   :theme (worg)
   :source-browse-url ("Github" "https://github.com/tumashu/tumashu.github.com")
   :personal-avatar "/media/img/horse.jpg"
   :personal-duoshuo-shortname "tumashu-website"
   :web-server-port 7654))

Chinese-pyim 's org-webpage config is a more complex example.

You can find more config options and theirs default values by commands:

C-h v owp/project-config-alist
C-h v owp/config-fallback

Publication

M-x owp/do-publication

Dependencies

1. emacs: this is an "of-course" dependency
2. 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. bash: the GNU Project's shell
4. git: a free and open source version control system
5. rclone: support to other remote locations, see rclone's overview for more information. (Optional)
6. mustache.el: a mustache templating library for Emacs
7. htmlize.el: a library for syntax highlighting (usually this library is shipped with emacs)
8. dash.el: a modern list library for Emacs
9. ht.el: a modern hash-table library for Emacs
10. simple-httpd: Extensible Emacs HTTP 1.1 server

Known issues

1. Currently the deletion change handler has not been implemented so if you deleted some org sources, you may have to manually delete corresponding generated html files.
2. URI path change detection is not available. That is, if you make a post with the URI "/blog/2013/03/25/the-old-post-name" and then change this value in your org source, org-webpage would be unable to detect that this has happened. 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.