Home > Emacs, Web > Set up a website using Emacs’ Org Mode

Set up a website using Emacs’ Org Mode

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

Advantages

A huge advantage is that now everything (including my CV, publications, and my ever-expanding academic FAQ) is in Org Mode. This means that changes are super-easy, even structural changes that I wouldn’t have attempted with HTML. So now when I need to update my CV, or add an FAQ, all I do is edit in Org Mode, something that I am very familiar with because I do it most of the day every day. I actually just categorized my FAQ using Org Mode in a matter of minutes. Linking with Org Mode is also incredibly easy, and the exporter knows how to handle links to files, headlines within files and internet urls. Also, since these documents are now in Org Mode, if someone wants a PDF version, all it takes is a few keystrokes to produce it.

Other huge advantages include features specific to Org Mode’s HTML exporting functions: Org Mode includes an option to specify MathJax display of mathematics: you enter LaTeX, publish with `org-publish’ and MathJax produces copy-and-pasteable MathML or LaTeX, and displays everything correctly according to the viewer’s browser. Javascript-controlled TOC views can make a page into an Emacs Info-style document. I chose this for my FAQ, since some of the answers were getting quite lengthy.

The weirdest thing is how easy this is once I figured it all out. After only a week of tinkering, I now have a website that I can update or make major changes to in a matter of minutes. It looks better, is easier to maintain and easier to configure.

Categories: Emacs, Web Tags: , , , ,
  1. January 18, 2012 at 05:55

    Reblogged this on quickgamer88.

    Like

  2. DTT
    February 20, 2012 at 20:08

    Reblogged this on Gà con's Blog.

    Like

  3. minshalll@acm.org
    December 22, 2013 at 18:33

    hi. i had to add “:publishing-function org-html-publish-to-html” to publish my .org files (otherwise i got an error “No publishing function chosen”). i’m using emacs 24.3.2.

    cheers.

    Like

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: