Create An Org Mode Blog (Static Site Blog)

How to create an org mode blog

Emacs is, of course, not only a text editor but also — with Org mode — a powerful publishing tool. You can use Emacs to author documents, create an editorial calendar, or even publish your own Org mode blog. Engineer your own static site blog generator? Yes.

What Makes a Blog a Blog

In order to create a blog from scratch, we should be clear about the basic requirements of a blog.

A blog typically consists of the following:

  1. An index of posts, most often sorted in reverse chronological order
  2. Regularly update with new content
  3. A syndicated feed, typically with RSS, so that readers can be notified when new content is published

These are, at the most basic level, the necessary elements of a blog; without one of these, you have merely a website.

We can do all of this with Org mode. But here’s the best part. You can start with this article. You’ll find that enthusiastic Emacs users all over the web have devised their own recipes for how to set up a blog. You have the maximum choice to try out all the different recipes you want.

How to Set Up Your Org Mode Blog

For a complete reference, check out the complete Org mode documentation node for publishing.

First of all, there are some decisions you need to make. Remember that your website files will originate as org files. (You need the raw org files that make up your base composition, and the resulting html files that become the org mode blog.) So pick two directories: one to store your org files and one to store the resulting html files. It might look something like this:

~/orgfiles/
~/html/

In this example, the orgfiles directory will hold the org files (and static web files like CSS stylesheets and images) and the html  will hold the converted html files (and the static web file will be copied over here as well).

Emacs lisp looks confusing to newcomers, but it’s best to think of it as a list processor. It’s best at taking lists of things and performing operations upon those items in the list.

Below, we are creating a list of items to be included in the website, and what operations are to be performed. For the first item, “org-files” we are telling Emacs that

  1. We have a bunch of Org files in a directory
  2. We want all these files converted to HTML and placed in another directory.

Next, we have a list of static files that we would simply like copied over to another directory. You can provide a list of file extensions to search for, but I have found on some systems these don’t always work. (I’m still testing it out.)

You can provide an individual file extension and this is sure to work. Org mode will search your project directory for files of that type and copy them over. (Both the multiple list extension and single variety are presented below for your perusal.)

(require 'ox-publish)
(setq org-publish-project-alist
      '(

       ("org-files"
       :base-directory "~/orgfiles/"
       :base-extension "org"
       :publishing-directory "~/html/"
       :recursive t
       :publishing-function org-html-publish-to-html
       :headline-levels 4  
       :auto-preamble nil
       ;:html-preamble "<header><h1><a href=\"index.html\">Would rather be on the beach...</a></h1></header>"
       :html-postamble "<hr><a href=\"/\">Home Page</a>"
       :html-head "<link rel=\"stylesheet\" href=\"style.css\" type=\"text/css\"/>"
       )

       ("org-static"
       :base-directory "~/orgfiles/"
       :base-extension "css\\|htaccess\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf\\|txt"
       :publishing-directory "~/html/"
       :recursive t
       :publishing-function org-publish-attachment
       )

       ("rss"
        :base-directory "~/orgfiles/"
        :base-extension "org"
        :rss-image-url "https://example.com/images/image"
        :html-link-home "https://example.com"
        :html-link-use-abs-url t
        :rss-extension "xml"
        :publishing-directory "~/html/"
        :publishing-function (org-rss-publish-to-rss)
        :section-numbers nil
        :exclude ".*"            ;; To exclude all files...
        :include ("index.org")   ;; ... except index.org.
        :table-of-contents nil
       )

       ("images"
       :base-directory "~/orgfiles/images"
       :base-extension "png\\|jpg\\|gif"
       :publishing-directory "~/html/images"
       :recursive t
       :publishing-function org-publish-attachment
       )

       ("font"
       :base-directory "~/orgfiles/font"
       :base-extension "ttf"
       :publishing-directory "~/html/font"
       :recursive t
       :publishing-function org-publish-attachment
       )

       ; the name of the publishing project, in this case "website"
; publish the org mode blog
("website" :components ("org-files" "org-static" "images" "font" "rss")) ))

How To Add The RSS Feed

The code needed for the RSS feed has already been included in the snippet above, which carries the whole website for you. Having an org mode blog, specifically, means that the RSS feed needs to added by you, this isn’t a content management system (exactly).

You must first make sure the that RSS “backend” for Org mode has been installed.

The easiest way to install this is to download the source from the GitHub repository, and then load the contents.

(load-file "~/path/to/org-rss/ox-rss.el")

Now, once you add this to your init file, and reload Emacs, your configuration will have the ox-rss backend available, and the main code snippet will build your website.

The configuration, as it stands, uses the main index.html file for the RSS feed. But you don’t have to do that if you don’t want to. You can use any file. But remember that the resulting file, which will contain the feed, will be the same file but with the .xml extension on it.

New headings updates in the index file will be interpreted as items in the XML (RSS) file. In order to get them indexed in reverse chronological order just add a new heading on top of the old ones.

Keeping Up With The Emacs

Check out these other resources from the support center:

No matter if you're a developer, system administrator, or simply a fan of SSH and command line, InMotion's Cloud Hosting plans provide a fast, scalable environment that is budget-friendly.

CM
Christopher Maiorana Content Writer II

Christopher Maiorana joined the InMotion community team in 2015 and regularly dispenses tips and tricks in the Support Center, Community Q&A, and the InMotion Hosting Blog.

More Articles by Christopher

Was this article helpful? Join the conversation!