website - Zettel

This is an explanation of how this website is built for future reference. Short story: The pages are written in Markdown and the respective HTML website is automatically generated by a static site generator (Hugo) every time I push to github (using github actions).

Although it looks like one website, each part (the main site, Kuchenwiki, Zettel) are actually created and maintained as separate websites, just using the same design and nearly identical settings.

One of my goals was to have a minimum of externally loaded content and style files, so I tried to incude everything in the website itself. I also do not use any cookies or tracking, these websites are mostly for personal reference and have no commercial interest.

Using hugo

Hugo is a static site generator (written in Go) that transforms Markdown content into html and css with some associated style files.

Each content page is a simple text file in Markdown format stored in the content/ folder (see e.g. here for a reference of the syntax)

Using some layout files allows to define how the generated html files will look like. In my case I took the pulp theme, cloned that repo to the themes/ folder and only slightly modified it (some details see below).

To generate the site locally, the hugo command can be invoked, which by default builds the site into the public/ directory. Alternatively, a small server can be started by hugo server -D. This produces the site on http:://localhost:1313 (by default) and will regenerate it after all relevant file changes automatically.

The contents of the public/ folder could now simply be moved to your hosting server to make the website available to the public. Instead I chose to host it at github pages and leave the site generation also to github.

Github pages and deploying via github actions

I use github actions to make a github runner build the site automatically whenever I push to the publish branch.

Go to the settings of the repository, and under Pages enable the branch gh-pages and its root directory to be published.

Then add a custom action script (I named it publish.yml) under .github/workflows/:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


name: 🚀 Publish Github Pages

on:
  push:
    branches:
      - publish
jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Git checkout
        uses: actions/checkout@v2
        with:
          submodules: true

      - name: Setup hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'

      - name: Build
        run: hugo

      - name: 🚀 Deploy to GitHub pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: ./public
          force_orphan: true

This will be triggered every time I push to the publish branch and run 4 steps:

checkout the websites repo
setup the hugo generator
generate the site with hugo
publish the content of the ./public directory to the root of the gh-pages branch

You can see that I rely on github actions by peaceiris to do the most crucial steps (setting up hugo and deploying). See also there for some technical details (like the first Deployment when using GITHUB_TOKEN). This simple setup allows to forget about most hassle and works pretty well, as long as the website is small (if not, you’d likely not want to regenerate the full website at every commit).

Mathjax for math typesetting

To get LaTeX-like typesetting of mathematical formulas, I use MathJax.

The pulp theme loads mathjax v2.7 which has meanwhile been superceded by v3. It also did no longer work correctly for me out of the box and relies on embedding the remote mathjax code.

Locally host Mathjax on the website

Therefore I cloned the current mathjax repo to obtain the current version. You then need to decide which functionality you want to use. Go to the es5 folder of the cloned repo and copy the desired parts to a custom folder of your website (under static/, e.g. static/mathjax/). I only want support for TeX-like syntax, so I chose the tex-chtml.js file and the input/ files related to TeX as well as the output/ files related to chtml. Copying this enlarges the repository by (in my case) 2.2 MB but I think that is still bearable.

Setup Mathjax in hugo

After I now host a Mathjax copy on the website, the next goal is to make it available for hugo. Following the mathjax docs I converted the old configuration to v3, and put that into a mathjax.html file under layouts/partials/ which looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<script>
window.MathJax = {
  tex: {
    inlineMath: [['$','$'], ['\\(','\\)']],
    displayMath: [['$$','$$']],
    processEscapes: true,
    processEnvironments: true,
    tags: 'ams',
    autoload: {
      color: [],
      colorv2: ['color']
    },
    packages: {'[+]': ['noerrors']}
  },
  options: {
    skipHtmlTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
    ignoreHtmlClass: 'tex2jax_ignore',
    processHtmlClass: 'tex2jax_process'
  },
  loader: {
    load: ['[tex]/noerrors']
  }
};
</script>
<script src="mathjax/tex-chtml.js" id="MathJax-script"></script>

Note that I enabled inline math with single $ as delimiter, which is not enabled by default (as it might clash with other uses of the $ character).

This partial is then embedded into the head.html partial (the header of each content site) with

1
2
3


  {{ if or .Params.math .Site.Params.math }}
    {{ partial "mathjax.html" . }}
  {{ end }}

This was sufficient to get it up and working in my case.

You then get nicely formatted math when typing TeX syntax in your markdown files, e.g. $e^{i \pi} + 1 = 0$, or even automatically numbered equations (due to the tags: 'ams' setting):

\begin{equation} \psi^j_k(x) = 2^{-j/2} \psi\left(2^{-j}x-k\right) \end{equation}

Search

The current search of pulp does not work for me, although at the current small state of the website it is not crucial.

Most search implementations I found rely on lunr.js (also the one from the pulp theme), I will probably try at some future point to get this working at least for the Kuchenwiki.

This guide seems to be helpful, as it also talks about minifying. Personally I used esbuild to host a minified copy locally. The further implementation into the site will have to wait.

Using your own domain

See the separate post on how to use DNS forwarding from your own domain to the deployed website on github pages

Conclusions

With this setup you can get text files with minimal effort rendered nicely on your website. Using Markdown and hugo shortcodes allows for quite some flexibility in formatting although I’ve used only very few of the available options.