30 Dec 2024

About the website

I think every personal blog that is somewhat custom built should have documentation written on its design philosophy and implementation. I see this as an extension of the free-software ideal; you should not only be allowed but also able to extent and modify another program to your needs.

Design

The website is written in Emacs and in org mode, because I find the markup to be intuitive, natural, and easy¹. I generally took a lot of inspiration from others using the same tooling as me, as well as from Gwern, Maggie Appleton and various other blogs and homepages I have read over the years. The colour scheme is a slightly adapted version of Protesilaos Stavrou’s modus themes and the paradise theme. I find them visually pleasing, and they are apparently very accessible to those with impaired vision. I use have used them in Emacs for a long time, and so they fit nicely visually on my desktop when editing content.

The primary font used is , made by Dmitry Krasny, Bonnie Scranton, and Edward Tufte. Code (Such as the TeX you just read) uses Protesilaos’ Iosevka Comfy font. On my personal machines I use the amazing Cartograph, but I can not afford to use it on the website. The titles are typeset Plantin.

Static website generation

The blog is genereted using org-static-blog. I have an elisp file that runs the necessary configuration code and acts like a declarative configuration for the deployment of the static site. It looks like this:

(require 'org-static-blog)

(setq org-static-blog-publish-title "Joar von Arndt")
(setq org-static-blog-publish-url "https://joarvarndt.se/")
(setq org-static-blog-publish-directory "~/Documents/blog")
(setq org-static-blog-posts-directory "~/Documents/blog/posts/")
(setq org-static-blog-drafts-directory "~/Documents/blog/drafts/")
(setq org-static-blog-enable-tags t)
(setq org-static-blog-enable-og-tags t)
(setq org-static-blog-image "https://joarvarndt.se/vonArndtCrestWhite.png")
(setq org-export-with-toc t)
(setq org-export-with-broken-links t)
(setq org-export-with-section-numbers nil)
(setq org-static-blog-index-length 5)
(setq org-static-blog-use-preview t)
(setq org-static-blog-preview-link-p t)

(setq org-static-blog-page-header
      "<meta name=\"Joar von Arndt\" content=\"Joar von Arndt\">
      <meta name=\"referrer\" content=\"no-referrer\">
      <meta name=\"viewport\" content=\"initial-scale=1,width=device-width,minimum-scale=1\">
      <script src=\"https://tinylytics.app/embed/xzJ638St84zSVeyVpBxf.js\" defer></script>
      <link href=\"static/style.css\" rel=\"stylesheet\" type=\"text/css\" />
      <link rel=\"icon\" href=\"static/favicon.ico\">
      <link rel=\"me\" href=\"https://github.com/JanJoar\" />
      <script src=\"https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js\" defer></script>
      <script src=\"static/sidenotes.js\" defer></script>
      <script id=\"MathJax-script\" async src=\"https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js\"></script>")


(setq org-static-blog-page-preamble "<div class=\"header\">
            <a href=\"https://joarvarndt.se/\"><img id=\"themeImageHeader\" src=\"vonArndtCrestBlack.png\" class=\"header-img\" alt=\"Crest\" width=\"50\"></a>
          </div>")

(setq org-static-blog-page-postamble
      "<div class=\"footer\">
            <ul>
            <li><a href=\"https://joarvarndt.se/about.html\">About\n</a></li>
            <li><a href=\"https://joarvarndt.se/archive.html\">Other posts\n</a></li>
            <li><a href=\"https://joarvarndt.se/now.html\">Now\n</a></li>
<script src=\"static/theme.js\" defer></script>

            <li><a href=\"https://joarvarndt.se/rss.xml\">RSS</a></li>
            </ul>
          </div>")

(setq org-static-blog-index-front-matter "<a href=\"https://joarvarndt.se/archive.html\"><h2>All Posts</h2></a>")

(setq org-static-blog-preview-ellipsis "<span class=\"ellipsis\">Continue Reading</span>")

(setq org-static-blog-enable-tag-rss t)

;; For syntax highlighting of code (Like this).
(setq org-src-fontify-natively t)
(setq org-html-htmlize-output-type 'css)
(setq org-src-preserve-indentation t)

(setq org-image-actual-width nil)

This loads the required javascript² and CSS for themeing, both of which you should have received if you’re reading this. I am a big fan of org-static-blog due to it’s simplicity³, extensibility (its just a simple HTML static site) and obvious org-mode support. I used to use Hugo, a widely praised static website generator, but it only has nominal org-mode support, it requires a special non-org-mode YAML frontmatter that I really dislike. When writing a post, I prefer to leave formatting mostly out of it, and with my main focus on text. Tinkering with the website’s appearance is great fun of course, but I like to keep the two as separate activities. Writing any sort of special syntax brings me out of the experience, and that is partly why I wrote my own javascript to create sidenotes out of basic pandoc (and therefore org-mode) style footnotes.

Sidenotes

The sidenotes are heavily inspired by Gwern and Tufte CSS, but the Gwern sidenotes.js is not portable and seems way too complex for my needs (it is 1150 lines long!!). In comparison, here is the the script that creates sidenotes. It is merely 70 lines long, including whitespace and comments. It also allows for easy reading on mobile, vertical monitors, and JS-free browsers, since if the dimensions are not adequate for displaying sidenotes or the javascript doesn’t run the content does not disappear. Instead it is shown as a footnote at the bottom of the page with bidirectional links between it and the reference. The Tufte CSS approach is admirable — relying only on pure HTML and CSS — but my aforementioned dislike of jumping between prose and “syntax” means that is is not an approach for me. I have however taken the liberty of inspiration from Tufte CSS in the CSS of sidenotes and margin notes. Margin notes are written in the form of an org-mode export block, and so have to be located at the beginning or end of paragraph.

This is how I write a margin note!

#+begin_marginnote
This is how I write a margin note!
#+end_marginnote

I can do this since org treats “special blocks” as a <div> with a synonymously named marginnote class. This can then be styled however you want using CSS. Margin notes are usually not as critical in my mind as foot/sidenotes, since they serve merely as a general guide to the text rather than an explicit pointed “reference”⁴. That’s why margin notes are not displayed on mobile devices. This is an opinionated change from Tufte CSS’ approach, where margin notes are instead treated as unnumbered sidenotes when there is no margin to display them in.

Hosting

The website used to be hosted on my own server at home, on an Intel NUC machine. Since a 25 day long downtime in June 2025 I have moved it to netlify. My internet is simply too unreliable to maintain uptime when I am away. I use loopia as my domain registrar, primarily due to having been recommended them from people I trust, however I have made no significant research into alternatives myself.

I use magit to interact with git and push changes to the blog to a remote repository that then causes netlify to update.

Footnotes:

Why would any markup not use “//” to italicise text? Markdown’s use of just asterisks is admirable, but unintuitive for reading in plaintext (Does two asterisks mean italic or bold?). Org mode’s choice of using __ to underline text is similarly elegant.

For dark/light mode, mathjax, and of course these sidenotes (But only if you are reading on a wide screen). Sadly the external mathjax reference makes this nontrivial javascript, but that is a sacrifice I am willing to make for easy and beautiful \(\LaTeX\) renderings.

From the repository:

Above all, I tried to make org-static-blog as simple as possible. There are no magic tricks, and all of the source code is meant to be easy to read, understand and modify.

⁴

Even if it is not a literal reference, but it may often be, especially when it comes to my academic writings.