I decided to start a blog, and I decided I should be doing it from org-mode in Emacs.

Why

I have a lot of ideas that I like to share. They end up in long strings of texts, facebook threads, reddit, whereever. This seems like a good way to focus my attention a bit.

As for why I should want to do it from Emacs, I like to use Emacs for any sort of document editing and this definitely qualifies.

Technologies

  • Hugo builds the static site from posts written in markdown and configuration in yaml.
  • Using gitlab pages, I don’t actually need to generate the site on my machine. I just git push and it happens automatically.
  • ox-hugo provides a very powerful export from org-mode to markdown for hugo.
  • I decided to use the even theme. I also considered cocoa-eh and hugo-wiki.

Getting things working

Pipeline for building the site

GitLab is few versions behind with Hugo. Also, sometimes it fails to get the base url correct. This is my .gitlab-ci.yml file:

image: monachus/hugo

pages:
  script:
  - hugo --baseURL "https://bcide.gitlab.io/"
  artifacts:
    paths:
    - public
  only:
  - master

Changes to the even theme

If you try to use themes as git submodules, gitlab gets very confused. Just make sure you remove the .git folder before committing.

ox-hugo uses arrays of authors by default, even if there is only one author. This caused the even theme to fail. I had to replace {{ .Params.author | safeHTML }} with {{ $length := len .Params.author | add -1 -}}{{ range $index, $element := .Params.author }}{{ $element | safeHTML }}{{if ne $index $length }}, {{ end }}{{ end }} in both /themes/even/layouts/partials/head.html and /themes/even/layouts/partials/post/copyright.html.

To get equation referencing to work correctly, in /themes/even/layout/partials/scripts.html, I replaced

<script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML"></script>

with

<script type="text/x-mathjax-config">
 MathJax.Hub.Config({
     displayAlign: "center",
     displayIndent: "0em",
     "HTML-CSS": { scale: 100,
		   linebreaks: { automatic: "false" },
		   webFont: "TeX"
     },
     SVG: {scale: 100,
	   linebreaks: { automatic: "false" },
	   font: "TeX"},
     NativeMML: {scale: 100},
     TeX: { equationNumbers: {autoNumber: "AMS"},
	    MultLineWidth: "85%",
	    TagSide: "right",
	    TagIndent: ".8em"
     }
 });
</script>
<script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-AMS_HTML"></script>

Update: I’ve changed waaay more things now…

Implementing a very basic wiki

I’m still not quite sure how to do this. I need to learn more about hugo themes.

Some tests

Just to have a place to come back and check if I’ve broken anything, the rest of this is just a bunch of tests.

Inline math \(x^2\)

Math display mode \[x^2\]

Equation environment

\begin{equation} \label{eq:test} \sum_{k=0}^\infty \frac{t^k}{k!} \end{equation}

I should be able to reference the equation: \eqref{eq:test}

Two things that are not working correctly with ox-hugo currently are \\ and \|. See issue 138. The following will render correctly after this issue is closed:

\begin{align} \|x+y\|^2 &= \langle x+y,x+y\rangle \\
&= \|x\|^2 + \langle x,y\rangle + \langle y,x\rangle + \|y\|^2 \end{align}

Here’s some code:

function α(t)
    return t.^2
end