Updated: November 27, 2011

Orgile: an Emacs Org-mode file parser and publishing tool.

Orgile is an Emacs Org-mode file parser and publishing tool written in PHP, which uses classOrgile.php, a rough Org-Mode file to HTML parser. I use the word ‘rough’ because I am not much of a developer.

Introduction.

I wrote Orgile.php and classOrgile.php so that I could focus on writing articles in Emacs and keeping my documents in their original Org-Mode format when uploading online. Orgile simply reads the .org files from the directory, and via classOrgile.php outputs the content to the browser as HTML. This actual article is this plaintext .org file. The standard1 Org-mode headers are used to create the article’s published date, title, author and article link. Orgile can output the full article, the description, a link list of post titles and an Atom XML feed. Parsing can be done on-the-fly but I implemented PHP Cache_Lite which caches the parsed .org pages in a cache directory to be served by the browser for efficiency sake. This can be easily turned off within Orgile.

My site toshine.org is built entirely with Orgile, plus some added content in the Orgile file and CSS. Orgile actually validates2 as HTML5 and the feed as a valid Atom 1.0 feed.

A plain vanilla setup can be seen here: orgile.toshine.org.

Orgile.php and classOrgile.php are free software: you can redistribute them and/or modify them under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Orgile.php, classOrgile.php and a full working installation can simply be pulled from github:orgile.

Note: classOrgile.php, the org-mode file to HTML parser can be used as a stand-alone PHP class in what ever tool you want. More so I would love someone to help me develop it further!

How it works.

Orgile is easier in function then it is to explain, but in summary…

1. The browser requests the URL.
2. The URL is rewritten calling index.php which passes the URL to the main orgile.php function.
3. Orgile.php builds the page depending what section was called in the URL.
4. If the URL contained an actual page address orgile.php fetches the physical .org file.
5. The .org file is parsed to HTML via classOrgile.php
6. The .org file headers provide title, description and date (also meta).
7. Orgile.php builds the entire HTML page with full headers and prints it to screen.

index.php simply calls the Orgile pagehandler() function:

include(‘site/orgile/orgile.php’); pageHandler();

The URL actually corresponds to the physical path of the .org file. This means that the physical structure of your site is the structure of your web pages, but the displayed link to the page is controlled by the header stipulated in the .org file. I like this as it means I can simply create or amend files in my directories and Orgile does the rest.

Thus http://toshine.org/etc/orgile-emacs-org-mode-file-html-parser-php-publishing-tool/ is actually calling /etc/orgile-emacs-org-mode-file-html-parser-php-publishing-tool.org or more precisely /srv/www/toshine.org/www/etc/orgile-emacs-org-mode-file-html-parser-php-publishing-tool.org, but the link title displayed is “Orgile: an Emacs Org-mode file parser and publishing tool.” This is controlled within the actual .org headers itself. The displayed date and summary/meta description of the article is also controlled by the header.

The .org file header:

#+Time-stamp: <2012-04-05 Thu 18:45 orgile-emacs-org-mode-file-html-parser-php-publishing-tool.org> #+TITLE: Orgile: an Emacs Org-mode file parser and publishing tool. #+AUTHOR: ‘Mash (Thomas Herbert) #+DATE: <2011-11-27 Sun 13:34> #+DESCRIPTION: Orgile is an Emacs Org-mode file parser and publishing tool written in PHP. It uses classOrgile.php which is the rough Org-Mode file to HTML parser. Orgile actually validates as HTML5 and the feed as a valid Atom 1.0 feed.

In terms of URL rewriting, I use lighttpd and so my rewrite rule looks like this:

url.rewrite-once = ( “^/([-a-zA-Z0-9]+)/$” => “/index.php?section=$1”, “^/([-a-zA-Z0-9/]+)/([-a-zA-Z0-9/]+)$” => “/index.php?section=$1&article=$2” )

The valid Atom 1.0 feed is created automatically from any existing directories you specify in orgile.php. You do not need to put anything in the feed directory itself, but the blank directory does need to exist for the URL to be called. The feed URL would look like toshine.org/feed.

Try it yourself.

The plain vanilla setup can be seen here: orgile.toshine.org and if you want to install it all you need to do is:

1. Clone (or download) the tool onto your webserver: https://github.com/mashdot/orgile
2. Edit the definitions in orgile.php: /www/site/orgile/orgile.php
3. Make sure you have the rewrite rules setup as above.
4. Point your domain to the setup.

This should give you enough to see how things work and my code has enough commentary to be readable and understood, but of course if you need any help let me know.

If you do happen to use the full tool or the class it would be nice for you to link back to me: Orgile made. Thanks.


Footnotes.

1 Standard apart from the Emacs ‘#+Time-stamp:<>’ header.

2 Apart from some citation errors: ‘The cite attribute on the blockquote element is not supported by browsers yet.’



etc:


  • Helpful.

    ATOM/RSS feed.
    Github.com:toshine-etc.

  • Comments.

    Send all to gro.enihsot@srettel. Also please do let me know if you spot any spelling or grammar mistakes.

  • Disclaimer.

    In terms of theological content, whatever sounds new is most likely wrong; and whatever sounds familiar has probably been said or written better by someone else. Simply examine the Scriptures to see if it is so. cf. Acts 17:11

  • Scripture quotations are from The Holy Bible, English Standard Version® (ESV®), copyright ©2001 by Crossway Bibles, a publishing ministry of Good News Publishers. Used by permission. All rights reserved.

  • Unless otherwise indicated, content on this site is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.

  • Doxology n. [Gr., praise, glory; to speak.] In Christian worship, a hymn in praise of the Almighty; a particular form of giving glory to God. [Webster 1828]

  • Why.

    I believe Jesus suffered once for my sins, the righteous for the unrighteous, that he might bring me to God. cf. 1 Peter 3:18.

  • The worth and excellency of a soul is to be measured by the object of its love. He who loveth mean and sordid things doth thereby become base and vile, but a noble and well-placed affection doth advance and improve the spirit into conformity with the perfections which it loves. The images of these do frequently present themselves unto the mind, and, by secret force and energy, insinuate into the very constitution of the soul, and mould and fashion it unto their own likeness.

    Henry Scougal. The life of God in the Soul of Man.