How to Create This Site

1 Publishing Evironment

This personal website is published with GNU Emacs + Emacs/Org-mode. Org-mode is a built-in mode in Emacs. Org-mode is originally a GTD tool, which has syntax very similar to Markdown. However, as it can export .org file to various formats(e.g. html, latex, docbook) as well as supporting export entire website, it seems Org-mode is much stronger than Markdown. Org-mode also handles figures, LaTeX equations, source codes very nicely.

1.1 GNU Emacs

For mac os users, you can use Aquamacs.

Emacs has a built-in tutorial which teaches you basically how to navigate within a file and how to use multiple windows. Go through that is enough for basic usage. For other commands, you can print out a Emacs Reference Card to check whenever you need.

Some very useful keys(C - Ctrl, M - Alt):

C-x C-fopen file
C-x C-ssave file
C-x bselect buffer

Emacs has many modes designed for special usage. Each mode has many key bindings doing task specific work. These keys usually begin with "C-c". Some modes also modify Emacs default keys such as indentation keys. Org-mode is such a mode most used originally for GTD workflow.

1.2 Org-mode

Org-mode is now built in Emacs. However, in order to let Emacs automatically recogonize .org file, we need to insert these lines into your emacs init file(usually ~/.emacs).

;; Org-mode settings
(require 'org-install)
(add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
(global-set-key "\C-cl" 'org-store-link)
(global-set-key "\C-ca" 'org-agenda)
(global-font-lock-mode 1)
(tool-bar-mode -1)

I was introduced to Org-mode by this article in Linux Journal. Just quickly go through it, then you will be used to org-mode syntax. This guide is also said to be a very good tutorial.

Here I would like to introduce how to include some very common elements in a document and how they look like in a exported html page.

1.2.1 Equation

This is a sample equation in \(\LaTeX\):

\Delta =\sum_{i=1}^N w_i (x_i - \bar{x})^2 \frac{y_i}{x_i}

\begin{equation} \Delta =\sum_{i=1}^N w_i (x_i - \bar{x})^2 \frac{y_i}{x_i} \end{equation}

1.2.2 Figure

Just Insert a link to your figure with C-c C-l like this:


Will generate a figure below:


1.2.3 Table

writing table in Org-mode is also very simple, you must try it yourself. Code:

#+ATTR_HTML: border="2" rules="all" frame="border"
| column 1 | column 2 | column 3 |
|        a |        b |        c |
|      1.4 |      2.5 |      3.6 |
|      1.4 |      2.5 |      3.6 |

Table in html:

column 1column 2column 3

1.2.4 Source code

I have inserted many source code into this page. It is very simple to do so in Org-mode. Just type "<" + "s" + <TAB> in a new line, Org-mode will automatically insert the folloing source code block for you:

#+BEGIN_SRC <language name>
<source code body>

We can use many other "<" + ? + <TAB> combinations to insert org-mode special struactral elements. It is called Easy Templates. This page gives a list of these templates.

This link lists the supported languages. We have used latex, lisp and org so far.

2 Setting the website

This part is a excerpt of a guide on how to publishing org file to html. I will introduce all the settings I made to create this site.

2.1 Prepare working folders

Suppose our home folder is ~/, we need to create a ~/www/ folder to store .org files and other images, css, etc. Another ~/public_html/ folder is created for publishing. Org-mode will automatically creates the same sub-folders as in the ~/www/, converts .org files into html files and saves all the html/image/css file into this ~/public_html/ folder.

2.2 Setting org-publish-project

We use org-publish-project command to export the site, a variable org-publish-project-alist needs to be configured. Let's insert the following lisp code .emacs file to set the variable, then the variable is set everytime emacs opens.

(require 'org-publish)
(setq org-publish-project-alist
        ("org-notes"               ;Used to export .org file
         :base-directory "~/www/"  ;directory holds .org files 
         :base-extension "org"     ;process .org file only    
         :publishing-directory "~/public_html/"    ;export destination
         ;:publishing-directory "/ssh:user@server" ;export to server
         :recursive t
         :publishing-function org-publish-org-to-html
         :headline-levels 4               ; Just the default for this project.
         :auto-preamble t
         :auto-sitemap t                  ; Generate sitemap.org automagically...
         :sitemap-filename "sitemap.org"  ; ... call it sitemap.org (it's the default)...
         :sitemap-title "Sitemap"         ; ... with title 'Sitemap'.
         :export-creator-info nil    ; Disable the inclusion of "Created by Org" in the postamble.
         :export-author-info nil     ; Disable the inclusion of "Author: Your Name" in the postamble.
         :auto-postamble nil         ; Disable auto postamble 
         :table-of-contents t        ; Set this to "t" if you want a table of contents, set to "nil" disables TOC.
         :section-numbers nil        ; Set this to "t" if you want headings to have numbers.
         :html-postamble "    <p class=\"postamble\">Last Updated %d.</p> " ; your personal postamble
         :style-include-default nil  ;Disable the default css style
        ("org-static"                ;Used to publish static files
         :base-directory "~/www/"
         :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf"
         :publishing-directory "~/public_html/"
         :recursive t
         :publishing-function org-publish-attachment
        ("org" :components ("org-notes" "org-static")) ;combine "org-static" and "org-static" into one function call

We can open the *scratch* buffer in Emacs, paste the above code, hit C-x C-e at the first and the last line to evaluate the code and set the variable without turning Emacs on and off.

2.3 Style control

The style is controled in several ways. Firstly, we could let a page use an external css style sheet to define its style. Secondly, org-mode provides some export options like whether or not displays toc, preamble, postamble, etc. Each way of style control, can be defined for a individual page or globally.

2.3.1 CSS style sheet

Create a stylsheet file org.css inside ~/www/css/ folder. Then insert the following line into your .org file defines the css style of this single page. Here I provide a sample CSS stylesheet. It is almost a copy of the org-mode default one.

#+STYLE:   <link href="css/org.css" rel="stylesheet" type="text/css">

2.3.2 Org-mode export options

Inserting some org-mode export options also changes the web page. Here is some useful options, the complete options is in the org-mode manual.

#+TITLE:       the title to be shown (default is the buffer name)
#+AUTHOR:      the author (default taken from user-full-name)
#+OPTIONS:     H:2 num:t toc:t \n:nil @:t ::t |:t ^:t f:t TeX:t ...
     H:         set the number of headline levels for export
     num:       turn on/off section-numbers
     toc:       turn on/off table of contents, or set level limit (integer)

2.3.3 Define styls globally

We can change the above settings for many files by edit the org-publish-project-alist in the ~/.emacs file, as we have done before. Or we can create another file level-N.orgcss, and I like to put it in ~/www/css/ folder. I name the extention as .orgcss but not .org due to I do not want to send these files to the publishing folder. Wrap those common lines defined in each .org file into this .orgcss file.

Sample: css/level-0.orgcss

#+AUTHOR:    author name

#+EMAIL:     author email

#+STYLE:   <link href="css/org.css" rel="stylesheet" type="text/css">

Then replace these line in each .org file with a single line:

#+SETUPFILE: css/level-0.orgcss

As you can see, the name or the .orgcss file "level-N" shows it is very useful for file in sub or sub-sub folders. We can define a different .css file location for all the .org files in the same level.

2.3.4 Bootstrap

This site also uses Bootstrap to control style. Bootstrap is a combination of CSS and JavaScript. You can customize your own Bootstrap settings via their official website. The style of this site "steals" files from Kris Jenkins's blog. I know this is not right. I will try to design my own style later.

Using Bootstrap is very simple. Just copy the necessary files into your directory, and insert some lines into your file.

css/level-0.orgcss file:

#+STYLE:   <link href="css/bootstrap.min.css" rel="stylesheet" media="screen"> ; new line
#+STYLE:   <link href="css/bootstrap-responsive.min.css" rel="stylesheet">     ; new line
#+STYLE:   <link href="css/org.css" rel="stylesheet" type="text/css">

Each .org file:

#+HTML: <script src="js/bootstrap.min.js"></script> ; new line

2.4 JavaScript

Org-mode provides a javascript org-info.js. To use it, save a copy of org-info.js into your js/ folder, and edit css/level-0.orgcss to add these lines:

#+LINK_HOME: index.html     ; the ``home'' link of an exported page
#+LINK_UP:   index.html     ; the ``up'' link of an exported page
#+INFOJS_OPT: path:js/org-info.js view:showall toc:nil ltoc:nil tdepth:2 mouse:#dddddd

The last line give org-info.js some options, like view type, toc display location, js path, etc. All the available options is here.

2.5 Summary

Up to now, we gradually built a .emacs file and some level-N.orgcss files, we have some .css file in our css/ folder and some javascript in js/ folder. A complete level-0.orgcss file looks like this:

#+LINK_HOME: index.html
#+LINK_UP:   index.html
#+STYLE:   <link href="css/bootstrap.min.css" rel="stylesheet" media="screen">
#+STYLE:   <link href="css/bootstrap-responsive.min.css" rel="stylesheet">
#+STYLE:   <link href="css/org.css" rel="stylesheet" type="text/css">
#+INFOJS_OPT: path:js/org-info.js view:showall toc:nil ltoc:nil tdepth:2 mouse:#dddddd

3 Publishing

Now Write some lines in the index.org file with the followingn header:

#+SETUPFILE: css/level-0.orgcss
#+HTML: <script src="js/bootstrap.min.js"></script>
#+TITLE: page tittle

Just type M-x org-publish-project <RET> then type org <RET> or use <TAB> to select a publish function from the list to publish. Org-mode will automatically convert .org file to html and transfer all the file to your destination directory. All links in .org file also automatically converted to relative links to files in publishing folder. So it's just like one key hit, all things done.

Last Updated 2013-03-08T23:19-0500.

© 2013 Qin He (http://www.seas.upenn.edu/~heqin) Thanks to Nan Sun for creating this site.