krater

This is a template to start building math-rich websites effortlessly.

Ancient Greeks placed large vessels named kraters at the center of the room during a symposium. An elected symposiarch would oversee the event by deciding the dilution of the wine in the krater and timing refills. Meanwhile, other symposyasts drank, talked, and enjoyed any pleasure the evening offered.

I hope this affords you to reproduce that, with ideas instead of wine.

Getting started

1. Click Use this template here or at the top of this page.
2. Pick a name for your new repo and create it.
3. Edit _config.yml replacing krater with your repo name in baseurl and paolobrasolin with your user name in url.
4. Wait for the first build to become green; you can observe its status at > Actions > Publish.
5. Enable GitHub Pages on branch gh-pages and folder /; you can reach the configuration panel at > Settings > Pages.

That's it! Your website is now visible at https://<USER_NAME>.github.io/<REPO_NAME>/

Usage

This is a Jekyll setup, so its excellent documentation fully applies.

Schematically, this is what krater gives you:

• A KaTeX setup composed of:
  • a custom page header in custom-head.html
  • a default configuration at katex in _config.yml
• An AnTeX setup composed of:
  • the jekyll-antex gem in Gemfile
  • a default configuration at antex in _config.yml
• A tweak to the kramdown configuration in _config.yml to let the previous components do their job.
• A GitHub Action workflow which compiles and publishes your website on GitHub Pages everytime something is pushed to the main branch.

As long as you keep these pieces in place the math rendering machinery will work.

Let's review some common tasks now.

Running on your machine

You will need a running LaTeX installation, including latexmk, dvisvgm and whatever engine and packages you plan on using. Chances are that if you're reading this you already have everything you need.

You will need to install Ruby.

After that, you can simply

# install dependencies
bundle
# run Jekyll
bundle exec jekyll serve

and your website will be available at http://127.0.0.1:4000/<REPO_NAME>/.

Local deployment

You might have reasons to build and deploy your website on your machine instead of using CI.

That's ok, and also pretty simple.

1. Disable the CI by deleting the .github folder and its contents.
2. Checkout a worktree based on the gh-pages branch inside the _site folder:

   git worktree add -B gh-pages _site origin/gh-pages

This makes it so that that the gh-pages branch (where the site must be deployed) will be directly accessible from the _site folder (where the site is built locally).

To deploy you can now just cd into _site, add your files, commit and push!

In case you want to undo this setup, this is the elegant way:

git worktree remove -f _site

Configuring CI

The CI workflow uses this action to setup TeX Live. If you require some less than common packages, just add them to the list in .github/texlive.packages and push to the repo. You can also change the scheme in .github/texlive.profile but I strongly advice against that if you're not sure what you're doing.

Kickstarting a blog/course/book

If you're familiar with Jekyll, you can proceed as usual. If you're not, all common tutorials apply.

If there's interest in some examples or a more specific template, HMU!

Plugins customization

krater installs all Jekyll plugins available in GitHub Pages via the github-pages gem in the Gemfile. This will help you if you're used to the standard features of GitHub Pages.

If you wish, you can be more selective and cherry pick only the plugins you need.

You can also any other Jekyll plugins you need: the build process runs in custom CI action and the usual limitations of GitHub Pages do not apply.

Theme customization

The default theme is minima but you can easily change that as long as you ensure custom-head.html still gets included.