### Archive

Posts Tagged ‘design’

## Set up a website using Emacs’ Org Mode

January 17, 2012 3 comments

Recently I decided that maintaining my homepage in HTML was getting too laborious: the primary problem was things like lists and hierarchies. I have used Emacs’ Org Mode for my daily agenda for almost five years, and decided that it was the right tool for organizing these structures. Org Mode allows you to view “your life in plain text,” which is, of course, the most versatile way to do so. What Org can also do is export your hierarchical documents to HTML, LaTeX and many other formats (including formatted ascii, which is very nice). Along with this is the feature org-publish that uses Tramp to transfer a set of exported HTML files (and other files) to another location.

## Configuring org-project-alist

Read the Org Manual’s section on org-publish: you can find a simple example there. A single variable called org-publish-project-alist’ configures all the stuff you need to publish an entire website. Here’s mine:

(setq org-publish-project-alist
'(("mysite"
:base-directory "~/Documents/web/"
:base-extension "org"
:recursive t
:section-numbers nil
:table-of-contents nil
:publishing-directory "/ssh:joel@example.org:~/public_html"
:style "")
("imgs"
:base-directory "~/Documents/web/imgs/"
:base-extension "jpg\\|gif\\|png"
:publishing-directory "/ssh:joel@example.org:~/public_html/imgs"
:publishing-function org-publish-attachment
:recursive t)
("etc"
:base-directory "~/Documents/web/"
:base-extension "css\\|bib\\|el"
:publishing-directory "/ssh:joel@example.org:~/public_html"
:publishing-function org-publish-attachment)
("docs"
:base-directory "~/Documents/web/docs/"
:base-extension "html\\|tex\\|bib"
:publishing-directory "/ssh:joel@example.org:~/public_html/docs"
:publishing-function org-publish-attachment)
("thewholedamnshow" :components ("mysite" "imgs" "etc" "docs"))))


After a few days of having this in my .emacs I decided this needed its own file, which I called “project.el” and placed in the home directory of my project.

Each one of the members of this list is a “project.” Projects can include other projects by using the “:components” property. Suppose my website’s files are in the directory “~/Documents/web/”. This is where I keep the actual org-mode files, css files and any other files I want to publish. The property “:publishing-directory” puts the exported files in the specified location, which is a tramp url. The trick is really the property “:publishing-function,” which tells org-publish’ how to treat the files. If left blank, this will translate the files into HTML. For .css files and other stuff you might link to (e.g. my .bib or tex .files, or images) you can use the function org-publish-attachment’, which does no translation.

The crucial part of this variable is then the last “project,” which has only a “:components” property. This includes all the other projects, and hence when I publish “thewholedamnshow” using org-publish’ my entire set of files is exported and uploaded.

## Directory Structure

Now I have all the sources for my website in one directory. Before I had used a highly hierarchical setup that made links very complicated. After realizing that I didn’t have actually that much content, I now have all the org files in the toplevel directory, with two subdirectories: one for images and one for special documents that are not in Org Mode. These are essays or LaTeX documents that are already finished works and I do not expect to change them.

I keep all the Org Mode source files in Bazaar. This greatly simplifies things. With project.el included along with the website, I can work on this on any machine as long as I evaluate that variable before I upload using org-publish’.