Create a website with Emacs and Jekyll
A static website based on Mobile jQuery

1 Why create a static website?

After years of creating CMS website for other people, I decided that this site should be different. A database and 20+ Mb of server-side code just seems excessive for a scale of site that I ever expect to create. Plus, I am a tinkerer - I want to edit the html, write the javascript, tweak the css. I spend my working life in Emacs, so the question is.. what is the most flexible way that I can create a website that allows me the maximum amount of flexibility while providing sufficient templating and modularity to avoid the spagetti code nightmare that every flat-file static website turned into in the bad old days?

Once I found out about Jekyll - the static website generator used for GitHub pages - the answer was clear.. Use Emacs org-mode to publish html files, then Jekyll to process the template/markdown and create the site.

2 Create a directory structure

I have create a direcotry in my home directory called www. In this directory, I have a sub-dir for each project (e.g. ~/www/project1 ~/www/project2 etc.). Inside each project direcory you need two directories - one for the .org files and another to publish the .html files into.

In Emacs, you will edit files in the project/org directory, publish html files to project/html and also run Jekyll in the this directory.

My directory structure for this site is shown below:

www
└── absrnd
    ├── html
    │   ├── _includes
    │   ├── _layouts
    │   ├── media
    │   │   └── css
    │   ├── _posts
    │   └── _site
    │       ├── blog
    │       └── media
    │           └── css
    └── org
        ├── media
        │   └── css
        └── _posts

The two main directories for creating .org blog files are the www/project/org directory (e.g. create an index.org file here) and the www/project/posts directory (where you create filenames in the format YYYY-MM-DD-blog-title.org)

3 Emacs org-mode publishing

The easiest way of managing the site is to use org-mode project publishing function to publish the org directory into the html directory.

You will need to setup the project in your .emacs file:

(setq org-publish-project-alist
      '(
  ("org-absrnd"
          ;; Path to your org files.
          :base-directory "~/www/absrnd/org/"
          :base-extension "org"

          ;; Path to your Jekyll project.
          :publishing-directory "~/www/absrnd/html/"
          :recursive t
          :publishing-function org-publish-org-to-html
          :headline-levels 4 
          :html-extension "html"
          :body-only t ;; Only export section between <body> </body>
    )

    ("org-static-absrnd"
          :base-directory "~/www/absrnd/org/"
          :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf\\|php\\|ico"
          :publishing-directory "~/www/absrnd/html"
          :recursive t
          :publishing-function org-publish-attachment)

    ("absrnd" :components ("org-absrnd" "org-static-absrnd"))
))

With the config as above, publish using

M-x org-publish absrnd

3.1 How to publish a project as HTML

Org-Mode can publish a project in many different formats, including HTML. To publish, use

M-x org-publish <project>

Or, when editing an org-mode file, use

C-c C-e X <project>

3.2 org-mode Babel code highlighting

To get syntax highlighting of source code in your blog, add the following to your .emacs file:

(add-to-list 'load-path "~/.emacs.d/htmlize")
(require 'htmlize)
(setq org-export-htmlize-output-type 'css)

You can include code snippets into your blog by using, For example:

#+BEGIN_SRC C
function foo() { bar(); }
#+END_SRC

3.3 Front Matter

To link your site together with Jekyll, add Front Matter to the start of your .org file. For example:

#+BEGINEXAMPLE

--- layout: post title: Create a website with Emacs and Jekyll subtitle: A static website based on Mobile jQuery excerpt: Managing a website using SVN, Emacs and Jekyll. ---

4 Mobile jQuery templates

The documentation on the Mobile jQuery site is excellent, and I basically got the templates for this website up and running by reading the getting started page!

5 Summary

This is a brief overview of how I got this site up and running, using a powerful tool-chain that gives me the flexibility to control every aspect of the site layout and content, version control, templating and produce a static website that is as fast as possible on my shoe-string webserver!

Next, I plan to add diagram creation and publishing..

6 Useful links

Author: Stuart

Created: 2016-07-10 Sun 17:32

Validate