BLOG(9)
BLOG(9)

Blorgging

This website has received a much-needed refresh, one that I’ve been putting off for years. While I’ve made a personal blog in the past (albeit all of them being short-lived), all of them have used Jekyll, a popular static site generator written in Ruby. This is fine and dandy, sure, but I don’t know Ruby, so I didn’t know how to maintain a Jekyll site well. Furthermore, I’ve always used some random theme I grabbed off of GitHub and slapped it on there with the might of Zeus. Again, worked, but wasn’t great, and didn’t reflect well on my competency as a developer if I couldn’t whip up a simple blog on my own.

This whole arc of using Jekyll happened in 2015-2016, and ever since then my site has been one of the following:

Enter org-mode for Emacs. While I’ve been using Emacs for the last three to four years, Org had always slipped my mind — I’d always kept a paper journal, and I preferred the “feel” of pen on paper, whatever that means. However, in an attempt to minimize my carrying load in preparation for university, I took notes in Org during a single lecture, and I was immediately hooked. In particular, Org feels more consistent than something like Markdown for simple note-taking, and has less (no) “dialects” e.g. GitHub or Pandoc flavored Markdown. The TechHOUNDS Wiki uses LaTeX, but that seems a bit overkill for a blog in my opinion.

Unfortunately, when I went to go rewrite my website using this wonderful new tool, I got lost in a sea of options ranging from existing static site generator extensions to archaic tools from the mid 2000s. I wanted a simple solution that handled within Emacs itself, and that didn’t rely on tons of variables. Thankfully, org-mode already provides the tools to do this!

Niceties are that code blocks are automatically formatted according to my Emacs theme, which saves the hassle of writing my own CSS. Also, I’m using MathJax, so this can happen:

\[ u(t) = K_pe(t) + K_i\int_0^te(\tau)d\tau + K_d\frac{\textrm{d}e(t)}{\textrm{d}t} \]

Implementation

The Elisp used for this is pretty simple, and understanding it is as an exercise to the reader it speaks for itself. Check it out in my dotfiles repository here, along with the rest of my Emacs configuration.

The only real weird thing I’ve done is host my own MathJax (to eliminate external dependencies where possible):

(setq blog/mathjax-options
      '((path "./static/mj/MathJax.js?config=TeX-AMS-MML_HTMLorMML")
        (scale "100") (align "left") (indent "2em") (tagside "right")
        (mathml nil) (font "Neo-Euler")))

I’m also using MathJax 2.x as it cooperates better with Org in my experience.

Furthermore, this site has an RSS feed, which generates via ox-rss. Again, read the config.

After loading this code, and setting your variables accordingly, you should be able to generate a site with M-x org-publish RET site RET. The CSS and other fluff are then adjusted to taste.

Things that are still broken

TODO blog.el must reload when blog/site-header-file and blog/site-footer-file update

This is a side effect of an odd bug I encountered. Note the lines:

(setq blog/site-header-raw (blog/add-html-file blog/site-header-file))
(setq blog/site-footer-raw (blog/add-html-file blog/site-footer-file))

which make this happen. I’m not particularly skilled with Emacs Lisp, so this is probably a pretty simple fix that I’m overlooking.

DONE Code blocks overflow on mobile (2020-01-17)

Relevant CSS:

pre {
    white-space: pre-wrap;
    word-wrap: break-word;
}

TODO Add dates to pages as well as tags

TODO There’s a trailing “-” after each element of a list for some reason?

Generated using org-mode

RSS