How I publish my wiki with org-publish

I use a Makefile to publish. I first read about how to do that here - How to blog with Emacs Org mode. All this does is call through to various publish functions in a new process - avoiding blocking Emacs while I'm publishing.

So for example, if I'm in a file in my org-roam project, I could do SPC c c (which triggers helm-make-projectile) and then the publish option. This triggers the publish make target. (You could also just run make publish from the command line of course).

The publish target is:

publish: publish.el
  @echo "Publishing... with current Emacs configuration."
  emacs --batch --load publish.el --funcall org-publish-all

This run emacs in batch mode, loading my publish.el as a library file, calling org-publish-all, and then exiting once finished.

In the previous case I'm calling one of org-publish's built-in functions. I can also call a custom function, e.g. with my graph target

graph: publish.el
  @echo "Graphing..."
  emacs --batch --load publish.el --funcall ngm/build-graph
        @chmod 755 graph.svg

This calls my own ngm/build-graph function in my publish.el.

I deploy the html files to my server with rsync via a make target, too.

rsync: publish.el
        @echo "rsyncing published site to hosting..."
        rsync -chavz /var/www/html/commonplace/ dloop:/var/www/commonplace/

You could have any kind of deployment step here, like a push to Netlify.

So, to re-iterate, the Makefile is just a non-blocking way to call various publishing functionality. With an extra benefit that I can have an 'all' target, that does a few steps in a row, e.g:

all: graph republish rsync

You can find my full Makefile here on Gitlab.

My publish.el file is where I put all of the bits of org-publish configuration, as well as custom publish functions I've written.

It's worth pointing out that this is a constant work-in-progress - you can always find the latest version here on Gitlab.

I have a few differents types of things in my publish.el.

Right at the beginning I started with the very simple CSS from Better Motherfucking Website. Since then I've tinkered with it a bit to make it look a little closer to my WordPress theme at doubleloop.net, and to get the Miller Columns stuff working.

To get the Miller Columns bits working, I copied and tweaked a bunch of stuff from Jethro's cortex ox-hugo theme that he uses for his braindump. It's mostly in page.js and URI.js.

One downside of putting stuff in a publish.el is that it isn't loaded by default as it would be if it's in your .emacs config. So you can't out-of-the-box then call stuff like org-publish-current-file. What I'm doing is just quickly opening publish.el and then evaling the buffer with , e b, then all the config and functions are available for use. That works for now, but I wonder if I can set it as part of dir-locals or in some kind of hook to get it eval'ed automatically whenever I'm in the project.

I actually don't run make all that often. It's too slow.

What I tend to do is org-publish-current-file on any new files I'm working on, and SPC c c and rsync. Then occasionally I'll do make all to rebuild and republish everything (which will include a new graph, sitemap, and update the backlinks on all the pages).

org-publish uses htmlize to do syntax highlighting of code blocks.

I found that this doesn't work immediately if you're publishing via –batch. htmlize is a package that needs to be included. It's included by default if you're publishing within the project when you're running Emacs, but not from –batch.

I learned from here https://gjhenrique.com/meta.html how to get htmlize to work from –batch.

Call org-publish-current-file with the universal argument (i.e. do SPC u first if you're in spacemacs) - that will force a republish of the file even if its actual content hasn't changed. So for example you'd do this if you want to update the backlinks on a published page.