org-mode for Static Website Generation

Tags: meta  website  emacs 

Some Context

This post no longer has a proper context; I am no longer using the following approach to generate my website. That said, I think it still contains some content that might be useful for someone else trying to use org-mode for static website generation.


I was unhappy with my previous website because the overhead of presenting content was high. It is my opinion that presenting content on a website should require as little non-essential work as possible; generating content (e.g., writing) is hard enough.

The Previous Site

The previous site used pagegen. Pagegen is a static web page site generator that relies on a site template file and a directory structure. Content for the site is stored in text markup files. The template can contain variables referring to components of the markup file. Explained at this level of detail, pagegen should be sufficient for my needs.

Realizing pagegen was not the right system for my needs came from using the markup language. Specifically, the textile variant that pagegen uses is something I have never seen before or since. Therefore, becoming familiar with the textile markup language to present content on my website would not be something I would likely find useful elsewhere.

To avoid sinking time into a technology with limited context, I generate my content in HTML then escaped all of it in textile. This increased the overhead of generating and presenting knowledge; creating simply structured content became a mess of XML. Naturally, I just avoided it.

Onward to org-mode

What is essential when presenting content for my site? The answer I arrived at is some simple way to structure content and some way to export this structure to HTML.

Org-mode has a configurable export system that will export org documents to other formats. There is some process for implementing conversions to target formats however, exporting to LaTeX and HTML has already been implemented.

After using emacs org-mode for a couple months, I realized that most of the structure I want when presenting content can be given using the most basic org-mode markup. Structures like sections, tables, lists, and typical text styles can all be described intuitively. Additionally, time spent understanding the markup and system in-depth would not be wasted; I have already committed to integrating org-mode into my daily habits.

Assuming emacs and the org-mode module are installed, to get org-to-HTML functionality to work add the appropriate configuration. I will develop this org-to-HTML export configuration in a peicewise fashion. This configuration should reside in a place such that emacs will execute it upon configuration.

First we must require org-mode’s publishing functionality.

(require 'ox-publish)

Editing my site content is a three phase process consisting of writing, editing, and publishing. During the writing and editing phases, I want to publish to my harddrive and review my work via a local path like file:///path/to/local/deployment/site/ in a browser. When I am satisfied with the content I publish it. I also want to structure content into different directories and refer to the content by relative paths. For example, I wanted all files to refer to a stylesheet in the css/ directory. I accomplished this by setting the base element in the head of all generated HTML files according to whether I want to view it locally or if I wanted to publish. How these variables are used to construct the head will follow shortly. Unfortunately, the solution below for toggling between the firt two phases and the last requires I change base-ref and execute my configuration via (load-file "file") (If you have a suggestion on how to fix this please leave a comment!).

(setf local-base-ref  "file:///home/dacosta/gitrepositories/documents/org/web/")
(setf chaosape-base-ref  "")
(setq base-ref local-base-ref)

From what I have gather, org-mode HTML exporting has two builtin publishing functions: org-html-publish-to-html and org-publish-attachment. The former converts org files to HTML then places the HTML in some destination directory and the latter copies the file to the destination directory. I have three pairs of variables defining content source and destination for org, css, and image files.

(setf chaosape-repo-location "/home/dacosta/gitrepositories/documents/org/web/")
(setf chaosape-css-location "css/")
(setf chaosape-img-location "img/")
(setf chaosape-src-location (format "%s%s" chaosape-repo-location "src/"))
(setf chaosape-src-css-location (concat chaosape-src-location chaosape-css-location))
(setf chaosape-src-img-location (concat chaosape-src-location chaosape-img-location))
(setf chaosape-dst-location (format "%s%s" chaosape-repo-location "build/"))
(setf chaosape-dst-css-location (format "%s%s" chaosape-dst-location chaosape-css-location))
(setf chaosape-dst-img-location (concat chaosape-dst-location chaosape-img-location ))

Org-modes HTML publishing functionality provides a configuration option to set HTML header files uniformly. Here I define a variable containing the content I would like place in the head of all generated HTML files. The base href must be set in the head so here we build the final head content using a format string and base-ref.

(setf chaosape-header
<base href=\"%s\">
<link rel=\"stylesheet\" href=\"css/chaosape.css\">

I also wanted a footer.

(setf chaosape-footer "
<a style=\"border-bottom: none;\" href=\"\">
  <img src=\"img/twitter.ico\" alt=\"chaosape on Twitter\"/>
<a style=\"border-bottom: none;\" href=\"\">
  <img src=\"img/bitbucket.png\" alt=\"chaosape on bitbucket\">
<a style=\"border-bottom: none;\" href=\"\">
  <img src=\"img/github.ico\" alt=\"chaosape on github\">
<a style=\"border-bottom: none;\" href=\"\">
  <img style=\"height: 32px; width:32\" src=\"img/aboutme.ico\" alt=\"chaosape on about me\">

There are three components associated with the project. The component recursively converts all org files in the source directory chaosape-src-location and places them in a corresponding directory with a root at chaosape-dst-location. The components and copy content from the directories chaosape-src-css-location and chaosape-src-img-location to chaosape-dst-css-location and chaosape-dst-img-location, respectively. Once this configuration is in place calling org-publish-all should generate content rooted at chaosape-dst-location. You may find additional information about this configuration here.

(setf org-publish-project-alist
      `(("" :components
         ("" "" ""))
         :base-directory ,chaosape-src-location
         :publishing-directory ,chaosape-dst-location
         :base-extension "org"
         :recursive t
         :html-head ,chaosape-header
         :publishing-function org-html-publish-to-html
         :with-author t
         :with-creator nil
         :with-latex t
         :export-with-tags t
         :export-creator-info nil
         :export-author-info nil
         :auto-postamble nil
         :table-of-contents nil
         :section-numbers nil
         :style-include-default nil
         :section-numbers nil
         :with-toc nil
         :html-postamble ,chaosape-footer
         :html-head-include-default-style nil
         :html-head-include-scripts nil
         :base-directory ,chaosape-src-css-location
         :publishing-directory ,chaosape-dst-css-location
         :base-extension "css"
         :publishing-function org-publish-attachment
         :base-directory ,chaosape-src-img-location
         :publishing-directory ,chaosape-dst-img-location
         :base-extension "jpg\\|gif\\|png\\|svg"
         :publishing-function org-publish-attachment

I wanted my index page to contain a listing of all of my blogs ordered by published date. The following function generates such a list based on org files in a directory named blog (Much of this code was lifted from steckerhalter then modified). We should be able to inline the output of this function by calling generate-bloglist in I was unable to get this to work correctly. However, I was able to get the dynamic block generation approach described here to work.

(defun org-dblock-write:generate-bloglist (params)
(let* ((dir "blog")
       (files (directory-files dir t "^[^\\._][^#].*\\.org$" t))
  (dolist (file files)
    (catch 'stop
      (let* ((path (concat dir "/" (file-name-nondirectory file)))
             (env (org-combine-plists 
                   (org-babel-with-temp-filebuffer file 
             (date (or (apply 'encode-time    (org-parse-time-string
                               (or (car (plist-get env :date)) 
                                   (throw 'stop nil))))))
             (last-modified-date (nth 5 (file-attributes file))))
        (plist-put env :file  (file-name-nondirectory file))
        (plist-put env :path path)
        (plist-put env :parsed-date date)
        (plist-put env :last-modified-date last-modified-date)
        (push env entries))))
  (dolist (entry (sort entries 
                       (lambda (a b) 
                          (plist-get b :parsed-date) 
                          (plist-get a :parsed-date)))))
    (format "* [[file:blog/%s][%s]]\n- %s\n- Last Modified on %s\n- Created on %s\n"
            (plist-get entry :file)
            (car (plist-get entry :title))
            (plist-get entry :description)
            (format-time-string "%B %e %Y" (plist-get entry :last-modified-date))
            (format-time-string "%B %e %Y" (plist-get entry :parsed-date)))))))

(add-hook 'org-export-before-processing-hook (lambda (backend) (org-update-all-dblocks)))

I found that the above code left some spurious text on the page. I am not exactly sure why and I am not familiar enough with org-mode to know how to remove it; I removed this text by writing a filter that modified the final output org-mode was to publish.

(defun org-html-remove-spurious-dynamic-block-code (string backend info)
  "Remove #+BEGIN:  generate-bloglist."
       (when (and (org-export-derived-backend-p backend 'html)
                  (string-match ".\+BEGIN:  generate-bloglist" string))
         (replace-regexp-in-string ".\+BEGIN:  generate-bloglist" "" string)))

(add-to-list 'org-export-filter-final-output-functions

I need the navigation menu to be placed uniformly in the content div element (all exported org structured text ends up within this div). I was able to get the menu placed correctly by writing another filter.

(defun org-html-add-navigation-after-content-div (string backend info)
  "Put the navigation menu inside the content div."
       (when (and (org-export-derived-backend-p backend 'html)
                  (string-match "div id=\"content\"" string))
         (replace-regexp-in-string "<div id=\"content\">" 
"<input type=\"checkbox\" id=\"nav-trigger\" class=\"nav-trigger\" />
<label for=\"nav-trigger\"></label>
<ul class=\"nav\">

        <li class=\"nav-element\"><a href=\"index.html\">home</a></li>
        <li class=\"nav-element\"><a href=\"cv.html\">cv</a></li>
<div class=\"content\">" 

(add-to-list 'org-export-filter-final-output-functions


I think this site setup will facilitate more frequent content creation. This is something I need to make a habit of if I intend to improve my writing skills. One gripe I have about this setup is its dependency on this dynamic block magic that requires me to write a filter to remove some spurious text.