Static Sites via org-publish

The directory structure for an org-mode project can be as simple as:

> ls /home/patrick/example/
bills.org
measurements.org
recipies.org

And org can be informed of its existence via:

(setq org-publish-project-alist
      `(("example-proj"
         :base-directory "/home/patrick/example"
         :base-extension "org")))

This snippet associates the directory containing org files with the project called example-proj. However it doesn't do much more than that.

Our goal is to generate HTML, so to make this useful we need to extend it somewhat:

(setq org-publish-project-alist
      `(("example-prog"
         :base-directory "/home/patrick/example"
         :base-extension "org"
         :recursive nil
         :publishing-directory "/home/patrick/example-html"
         :publishing-function org-html-publish-to-html)))

The options we've added should be self-explanatory, but if not, refer to the documentation.

Once org-publish-project-alist is updated, instructing emacs to publish our org as HTML is a call to (org-publish "example-prog" t). This gives us the following:

> ls /home/patrick/example-html/
bills.html
measurements.html
recipies.html

Much more useful! But still not ideal as we lack an index.html.

Thankfully, we can add options to our project-alist in order to have org-mode produce a sitemap with the name index:

(setq org-publish-project-alist
      `(("example-prog"
         :base-directory "/home/patrick/example"
         :base-extension "org"
         :recursive nil
         :auto-sitemap t
         :sitemap-style list
         :sitemap-title "Example Project"
         :sitemap-filename "index.org"
         :publishing-directory "/home/patrick/example-html"
         :publishing-function org-html-publish-to-html)))

;; REMINDER -- to publish the project:
(org-publish "example-prog" t)

Which when published results in the following structure (that is perfectly suitable to place in /var/www/html/):

> ls /home/patrick/example-html/
bills.html
index.html
measurements.html
recipies.html

There are far more options for how the sitemap is generated. The documentation explains each option well.

Of particular interest is :sitemap-style (we've used "list" here, and for a particular reason). And if you are building a blog, you will also want to look at :sitemap-sort-files.

Building a website often involves tree structures. The index branches into categories - posts grouped by year, recipies grouped by ingredients, music grouped by artist.

This creates a bit of a problem with everything under a single project. Our sitemap relates purely to the files within /home/patrick/example-html/, but if we were to turn recipies.org into a directory, it would currently be ignored.

There are two solutions to this I'd proffer.

1. Change :recursive nil to :recursive t, and change :sitemap-style list into :sitemap-style tree. This will have org-publish descend the directory tree and publish each org file it finds. The sitemap will then be structured to match the directory tree.
2. Create a recipies subproject that is a constituent of the example project.

The former is very simple, but the latter is incredibly flexible. We're going to look exclusively at the latter here, and we're going to start by restructuring our files and directories:

While this is all great, and we have something that looks like a website - we aren't done yet.

Websites without images are fewer and far-between these days. So we need to consider static assets.

As always, there's more than one way to skin a cat, but I find it intuitive to extend our project further:

(setq org-publish-project-alist
      `(("index") ;; SNIP
        ("recipies") ;; SNIP

        ("static"
         :base-directory "~/website/static"
         :base-extension any
         :recursive t
         :publishing-directory  "~/website/html/static"
         :publishing-function org-publish-attachment)

        ("website" :components ("recipies"
                                "index"
                                "static"))))

;; REMINDER -- to publish the project:
(org-publish "website" t)

Changing the :publishing-function to org-publish-attatchment results in org-publish performing a simple copy. I suspect that this is not entirely performant for very large sites with many assets - but I've yet to encounter an issue.

This does however require one small change in behaviour, as org-publish really does not like broken links.

For example, for a recipie to reference an image:

#+caption: Crème de menthe
[[file:../static/images/recipies/creme-de-menthe.jpg]]

Or, if preferred:

[[https://my.website.tld/static/images/creme-de-menthe.jpg][Crème de menthe]]

I would advocate for the former, as captions are added to the generated HTML, and the whole image+caption can be styled with the figure CSS class.

Which finally leads to styling.

By default, org-publish does add minimal styling. But if you're like me, you'll want to change it.

This can probably be done in a nicer way, but my method of approach is to inject a link to a stylesheet in the static directory.

For example:

`(("index"
   :base-directory "~/website/org"
   :base-extension "org"
   :recursive nil
   :publishing-directory "~/website/html/"
   :publishing-function org-html-publish-to-html
   :with-toc nil
   :auto-sitemap nil
   :html-head-include-default-style nil
   :html-head "<link rel=\"stylesheet\" href=\"../static/stylesheet.css\" type=\"text/css\"/>")

Finding the classes org-mode specifies for HTML elements is best done using web inspector tools in your browser.