Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/emacsorphanage/org-page

[INACTIVE] A static site generator based on Emacs and org mode.
https://github.com/emacsorphanage/org-page

Last synced: 9 days ago
JSON representation

[INACTIVE] A static site generator based on Emacs and org mode.

Awesome Lists containing this project

README 

        
#+TITLE:     Org-page: Static Site Generator

#+AUTHOR:    Kelvin Hu

#+EMAIL:     [email protected]

#+DATE:      2012-08-23



* Sorry folks, This project is not under active development any more.



* Introduction



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



  Org-page provides the 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/hashover)

  10) Website traffic analytics (implemented using google analytics)

  11) Index/about page support (auto generated if no default is provided)

  12) Site preview

  13) 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 an example.*



** Workflow



   1. Specify a git repo where the org source

      files will be on the "source" branch and the generated html files

      will be on the "master" branch (the branch names can be

      customized). Repos may be created manually or by

      org-page's =op/new-repository= command.

   2. Specify a "base commit" (the most recent prior 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 then be marked for publication.

   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 of these kinds of changes but since deletion does not happen often, org-page has not implemented it yet*

   5. Update the index page for each category and tag.

   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 the "doc" folder.*



** Installation



   Org-page is now available from the famous emacs package repo [[http://melpa.milkbox.net/][melpa]]

   so the recommended way is to install it through emacs' package

   management system. For more info about installation, please see

   *quick-guide.org* in the "doc" folder.



** Configuration



   Add the following lines to 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, duoshuo or hashover

   : (setq op/personal-disqus-shortname "your_disqus_shortname")

   : (setq op/personal-duoshuo-shortname "your_duoshuo_shortname")

   : (setq op/hashover-comments t)

   : ;;; the configuration below are optional

   : (setq op/personal-google-analytics-id "your_google_analytics_id")



** Publication



   Evaluate the following code to publish your changes:



   : (op/do-publication nil "HEAD^1" "~/org-pub/" nil)



   or just



   : (op/do-publication)



   You can also run it interactively: =M-x op/do-publication =



*NOTE: Org-page does NOT commit your org files to git, so you have to commit them

manually before you run this command.*



** Site preview in browser



   Just run =M-x op/do-publication-and-preview-site =, the site will be published in =~/.op-tmp=, then it will be previewed in browser automatically.



* 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 = 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

  8. [[https://github.com/skeeto/emacs-web-server][simple-httpd]]: A simple Emacs web server is required for site preview

  9. [[https://github.com/rejeep/git.el][git.el]]: An Elisp API for programmatically using Git



* 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 generated html files.

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