Publishing Org-mode files to HTML

The notes component publishes all the Org-mode files to HTML. Hence the publishing-function is set to org-publish-org-to-html. Here is an example of the notes component:

("org-notes"
 :base-directory "~/org/"
 :base-extension "org"
 :publishing-directory "~/public_html/"
 :recursive t
 :publishing-function org-html-publish-to-html
 :headline-levels 4             ; Just the default for this project.
 :auto-preamble t
 )

Note, that headline-levels may be adjusted on a per file basis to overwrite the default.

The most important settings here are:

The static component just copies files (and their folders) from :base-directory to :publishing-directory without changing them. Thus let’s tell Org-mode to use the function org-publish-attachment:

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

Note that :publishing-function is set to org-publish-attachment.

To publish all with one command, we add the publish component. For this component I usually drop the suffix and just use the basename of the project.

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

Now M-x org-publish-project RET org RET publishes everything recursively to ~/public_html/. Target directories are created, if they don’t yet exist.

The good message is yes, we can. Just one little hump. Since we’ve put the definition for our publishing components in the *scratch* buffer, again, make sure all the components are enclosed by the lines

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

       ;; ... all the components ...

      ))

Move to the end of the first line and press C-x C-e to load org-publish. Now go to the end of the last line and press C-x C-e again. Repeat the last step after every change to your org-publish-project-alist.

To publish your Org-mode files just type M-x org-publish-project RET org RET or use one of the shortcuts listed in the manual. If nothing went wrong, you should now be able to point your browser to http://localhost/~user/, if mod_userdir is set up. If not, simply navigate to file:///home/user/public_html (you might use file -> open from the file menu of your browser.

The first choice is the export options template on top of the file. When in an Org-mode file, you may insert basic information using C-c C-e # (org-export-dispatch) plus “template”. You will be prompted for a template choice. “default” will provide a template for common options, and “html” will provide a template for HTML-specific options.

WARNING: Do not copy lines from the sample output below into your files. The template might change from release to release. Instead, insert a template as above and delete any entries that are not applicable.

The default option inserts the following lines:

#+TITLE: filename with the extension omitted
#+DATE: <2013-06-04 Tue>
#+AUTHOR: Your name
#+EMAIL: Your email address
#+OPTIONS: ':t *:t -:t ::t <:t H:3 \n:nil ^:t arch:headline author:t c:nil
#+OPTIONS: creator:comment d:(not LOGBOOK) date:t e:t email:nil f:t inline:t
#+OPTIONS: num:t p:nil pri:nil stat:t tags:t tasks:t tex:t timestamp:t toc:t
#+OPTIONS: todo:t |:t
#+CREATOR: Emacs 24.3.50.3 (Org mode 8.0.3)
#+DESCRIPTION:
#+EXCLUDE_TAGS: noexport
#+KEYWORDS:
#+LANGUAGE: en
#+SELECT_TAGS: export

and the html option will add the following:

#+OPTIONS: html-postamble:auto html-preamble:t tex:t
#+CREATOR: <a href="http://www.gnu.org/software/emacs/">Emacs</a> 24.3.50.3 (<a href="https://orgmode.org">Org</a> mode 8.0.3)
#+HTML_CONTAINER: div
#+HTML_DOCTYPE: xhtml-strict
#+HTML_HEAD:
#+HTML_HEAD_EXTRA:
#+HTML_HTML5_FANCY:
#+HTML_INCLUDE_SCRIPTS:
#+HTML_INCLUDE_STYLE:
#+HTML_LINK_HOME:
#+HTML_LINK_UP:
#+HTML_MATHJAX:
#+INFOJS_OPT:

All we have to do now is to alter the options to match our needs. All the options are listed in the wonderful Org-mode manual. Note though, that these options are only parsed on startup (i.e., when you first open the file). To explicitly apply your new options move on any of those lines and press C-c twice.

Also, CSS style variables may be using a special section may be #insert/appended to Org-mode files:

* COMMENT html style specifications

# Local Variables:
# org-html-head: "<link rel=\"stylesheet\" type=\"text/css\" href=\"css/stylesheet.css\" />"
# End:

css/stylesheet.css suits the needs for a file in the root folder. Use
../css/stylesheet.css in a subfolder (first level),
../../css/stylesheet.css for a file in a sub-sub-folder.

Also, these level-N files give us the chance to easily switch between different export setups. As an example, we could have a separate stylesheet and org-info.js setup for presentations, and put the appropriate options in a file named level-0-slides.org:

#+INFOJS_OPT: path:org-info.js
#+INFOJS_OPT: toc:nil view:slide
#+STYLE: <link rel="stylesheet" type="text/css" href="slides.css" />

Now it’s as simple as typing ’-slides’ to change the appearance of any file in our project.

Once we get tired of copying the static files from one project to another, the following configuration does the trick for us. We simply add the inherit component, that imports all the static files from our ~/org/ directory ⁴. From now on, it will be sufficient to edit stylesheets and scripts just there.

 ("B-inherit"
  :base-directory "~/org/"
  :recursive t
  :base-extension "css\\|js"
  :publishing-directory "~/public_html/B/"
  :publishing-function org-publish-attachment
 )

 ("B-org"
 :base-directory "~/B/"
 :auto-index t
 :index-filename "sitemap.org"
 :index-title "Sitemap"
 :recursive t
 :base-extension "org"
 :publishing-directory "~/public_html/B/"
 :publishing-function org-publish-org-to-html
 :headline-levels 3
 :auto-preamble t
 )
 ("B-static"
  :base-directory "~/B/"
  :recursive t
  :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf"
  :publishing-directory "~/public_html/B/"
  :publishing-function org-publish-attachment)

 ("B" :components ("B-inherit" "B-notes" "B-static"))

Note, that the inheritance trick works for non org directories. You might want to keep all your stylesheets and scripts in a single place, or even add more inheritance to your projects, to import sources from upstream.

Note also, that B-inherit exports directly to the web. If you want to track the changes to ~org/*.css directly in ~/B, you must ensure, that B-inherit is the first component in B since the components in B are executed in the sequence listed: first get the new stylesheet into B, then execute B-static.

Org-modes great publishing also generates a recursive sitemap. Its name defaults to sitemap.org, which get’s in our way, since we have a real startpage as sitemap.html ⁵. Fortunately there is a configuration option to change the name of the generated sitemap. To generate the sitemap, add these lines to the notes component:

 :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'.

The sitemap will reflect the tree structure of the project. To access the sitemap easily, we could do two things:

1. Setup the ’UP’ link of the Startpage to link to sitemap.html (see next section),
2. use the ’#+INCLUDE: sitemap.org’ directive. Most of my Org-mode files contain a chapter called “Links” at the end of the file, which contains a subsection Sitemap that in turn just consists of that diretive. For the index.org files in the root directory, I include the sitemap as the first section.

You can also change the position of folders with :sitemap-sort-folders, this can be set to last or first (default), to display folders last or first.

Another way to get additional links to navigate the structure is org-info.js. Let’s set it up like this (either in every file, or in org-level-N.org, where N > 0):

#+HTML_LINK_UP: index.html

This makes the little UP link (’h’) point to the index.html in the current directory.

The index.org in the root of the project has the index file as section 2 (which I may reach pressing ’n’ then), and the same option set like this:

#+HTML_LINK_UP: sitemap.html

For an index.org in a subdirectory:

#+HTML_LINK_UP: ../index.html

The HTML_LINK_HOME always points to the same file:

#+HTML_LINK_HOME: http://localhost/~user/index.html

Please consider replacing the last one with a relative path (which will be different for every level of subdirectories).

No matter where we are, we may always press H n and we face the sitemap. No matter where we are, we may always press h to move up the tree.