Publishing with Org-Publish

Although I’ve been using org-mode for some years now, I only recently started to make use of the features of org-publish. I had started out in org-mode with simple outlining, and then, in the Emacs way, moved on to TODOs, agendas, and then creating my own extensions and customizations, many of them suitable to my main occupation of writing novels and stories.

(Like someone said on-line, 90% of Emacs users have unusual customizations. The other 10% have really unusual customizations.)

But getting back to org-publish; I wanted to put some things on-line about my Emacs experiences (hence this “35 Years of Emacs” series), and I also wanted to put other things on-line just so they would be available to friends, collaborators, etc.

Now, my Checker Maven blog is done in a typical manner, with a CMS, and although I use Emacs tools, it isn’t in any way Emacs-based. A pity, but I needed the full facilities of a content management system.

But shouldn’t blogging about Emacs be Emacs based? Come on now! And since most of my computer life is lived in Emacs, it all just made sense.

There are a number of options, and if you search on-line you’ll find all sorts of schemes for getting things from Emacs to your web site or blog host. I started out with a new Google Blogger entry and used org-mode to compose posts, export them to text, and email them to Blogger. It worked but it was multi-step. Now, I could have automated the steps, but the results weren’t very exciting, and Blogger munges important things like indentation in Elisp code.

Of course the answer lay in front of me all the time.

I do have my own web hosting account with GoDaddy. (No, they are nowhere near as bad as some people make them out to be. I’ve been with them for over a dozen years and have had very few issues.) So why not publish to my own web site?

That turned out to be easy with org-publish.

I did some research and found some sample configurations. These were relatively straightforward and easy to understand, and I had everything adapted and set up for basic operation in an hour or two.

So what do you do? You write in org-mode like you always do, and then tell org-publish to publish your stuff. And it does. And that’s it. It’s on-line and ready to go.

Of course, it’s Emacs, and there is endless tweaking and customizing if you wish (and you know you do). The pages I’m putting up right now are extremely plain; I haven’t bothered with custom CSS yet, although I certainly will get to that. I’ve only just scratched the surface of org-publish, but that’s already been enough for me to get a lot of things on-line quickly, in a usable, legible form, even if nothing fancy to look at.

(highly incomplete) (And that’s another thing, you can publish what you have and then easily augment it at any time. Just write more stuff, press a few keys, and it’s done.)

I won’t try to do Yet Another Tutorial. Go here instead:

http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.html

This tutorial is comprehensive and easy to follow, and will get you going in much less time than you might expect.

And that’s the first trap. It is so easy to put things on-line with org-publish. It will even build your site index for you to make all your new things easy to find. But be careful. You can publish some real tripe in a real hurry. You know: unedited, unchecked, misspelled, incoherent; the whole nine yards.

It depends how you do things. If you automate so that org-publish will publish everything new or changed in a given project directory, you really might want to think about doing drafts in a separate directory and then moving them to the publication directory when, you know, you’ve actually made them, uh, ready to publish.

There’s no one answer to this, but I like to do things like this.

~/organize
    /publish
      /project1
        (series of *.org files)
        /graphics
        /other
        /drafts
           /graphics
           /other
     /project2
      etc. etc.

In my setup, I publish the *.org files, and the stuff in the ’graphics’ and ’other’ subdirectories. (See my sample configuration file, when I get around to including it.) ’graphics’ is, well, graphics. ’other’ will eventually be css and perhaps javascript.

Notice I have ’graphics’ and ’other’ duplicated under ’drafts’. This is so that the drafts have correct and verifiable links to included graphic and other content. I need to mirror the publication structure to make this happen. When I’m ready, I copy (or move) everything up.