cryogen-chota

cryogen-chota is a cryogen theme that...

• looks simple, yet modern
• handles different viewport sizes (responsive design)
• automatically detects light/dark mode
• is accessible (use of ARIA where necessary, tested using IBM Equal Access Accessibility Checker, wave and axe)
• makes no requests to external services*
• is fairly small in size (my personal blog's home page is a ~20 KiB download. On a post with comments enabled and hljs themes, this goes up to 40 KiB)
• supports heading anchors (requires a cryogen extension like this)
• can be used without JavaScript**
• provides proper license notices and attribution for included components
• supports Mastodon as a provider for embedded comment sections
• supports integration of openring

*unless the Mastodon comment integration is used, in which case users will be asked for their consent first.
**minus highlightjs, klipse and the embedded comment section. A link to the comment thread on Mastodon is still displayed, though.

This theme was created out of perpetual procrastination, boredom and a sprinkle of discontent with existing cryogen themes (or lack thereof). It uses the self-proclaimed CSS "micro framework" (it's a library, really) chota.

Feedback and suggestions for improvements are appreciated. But please be gentle, I am not a web designer 🙂

Screenshots

I use this theme for my personal blog – check it out for yourself.

Here's a taste:

Use

Simply download/clone this repository and put its contents in a directory in themes/, e.g. themes/chota, then set :theme in your config.edn to "chota".

Mastodon Comments

To enable Mastodon comments, simply add the :comments key to your post's front matter. You have to pick a post that will serve as the "original post" for the comments.

{:comments {:instance "chaos.social"    ;; the mastodon instance
            :author "johnny"            ;; OP's username on that instance
            :id "111085941141595246"}   ;; Post ID 
 ...}

The above config would use this post as the comment section.

openring

openring is a small tool that can act as a "recommendation" tool for blogs. It will take a bunch of RSS feeds as sources and use some of the latest articles to generate some HTML using a template. Enable it using :openring? true.

Here's what it looks like if you use it with this theme:

It is displayed below the comments (if enabled) on each post.

The theme will look for a file called webring.html in the html folder and use it as the component for this section. It can't call openring for you, so how you generate this file is essentially up to you. The template used in the screenshot above can be found in html/openring-template.html and can be thrown at openring as-is.

For a sample setup that generates the webring from within the generator code, see my blog. It has an openring alias defined in its deps.edn that does this job.

Automatic Heading Anchors

As mentioned above, this theme can handle heading anchors (permalinks that jump to a specific heading). This cannot be done using the theme alone, though; custom cryogen code is required.

Note that for newer cryogen versions, you have to replace :update-article-fn with :postprocess-article-html-fn (also, you have to adjust server.clj as mentioned in a comment on the gist).

Customisation

There are some "native" customisation options as well as some common adjustments that require you to edit the template. The most important things are described in this section.

Language

While this theme is unfortunately not localised right now, you can still set the language of your page using the :lang key in your config. It defaults to "en". Keep in mind that this has accessibility implications.

:lang "en"

Disabling highlight.js

If you don't want to include a highlight.js script on your site, you can set :disable-hljs? to true in your config. This may be of interest if you decide to do your syntax highlighting ahead of time.

Footer Links

This theme lets you display a bunch of links in the page's footer – these links are fully configurable.

For example, here's my set of links:

This can be configured in your config.edn using the footer-links key:

{:footer-links [{:uri "https://github.com/JohnnyJayJay/JohnnyJayJay.github.io"
                 :icon "img/github.svg"
                 :text "View blog source"}
                {:uri "https://matrix.to/#/@johnny:yatrix.org"
                 :icon "img/matrix.svg"
                 :text "Contact me on Matrix"
                 :title "@johnny:yatrix.org"}
                {:uri "https://chaos.social/@johnny"
                 :icon "img/mastodon.svg"
                 :text "Follow me on Mastodon"
                 :rel "me"
                 :title "@johnny@chaos.social"}
                {:uri "https://ko-fi.com/johnnyjayjay"
                 :icon "img/kofi.svg"
                 :text "Buy me a coffee"}]}

Link text, link title, link URI and the rel attribute (for example for verification on Mastodon) are configurable.

Two things regarding icons:

• Icons should be black (transparent background). The theme will change them to white in case dark mode is active.
• The icon path is absolute, but without the leading / (the block prefix + / will be prepended).

highlight.js

This theme ships with a custom highlight.js distribution that includes support for some, but certainly not all possible languages. If you're missing a language, feel free to just replace the distribution in js/highlight.min.js with your own. The highlight.js download page offers a way to get exactly the languages that you want.

Similarly, if you want to use different highlight.js themes, you may simply replace css/hjs-light.min.css and/or css/hjs-dark.min.css. The default are the two a11y themes that come directly with highlight.js.

Content License

Do you want to add an explicit license to your blog posts? This theme allows you to define one using the :content-license key in your config.edn.

{:content-license {:name "CC BY-SA 4.0"
                   :uri "https://creativecommons.org/licenses/by-sa/4.0/"}}

This will be displayed in the "Licensing & Attribution" section of the footer. If it is not set, "All rights reserved" is shown there instead.

Colour Scheme

The colour scheme of this theme can be adjusted by manually editing css/base.css. If you just want to get rid of all the green, you'll have to edit --font-color (font), --color-primary (links and buttons) and --bg-color (background), for dark and light mode respectively. Depending on your colour choice, you may also want to adjust the greyscale colours.

License

The theme (that is, everything in html as well as css/base.css) is licensed under the MIT license, Copyright © 2023 JohnnyJayJay.

This repository also contains materials from third parties:

• css/chota.css (chota): Copyright © 2017 Jenil Gogari. Licensed under an MIT License.
• js/comments.js, css/comments.css (adapted from this blog post): Copyright © Carl Schwan, JohnnyJayJay. Licensed under a GPL-3.0-or-later license.
• js/purify.min.js (DOMPurify): Copyright © 2023 Dr.-Ing. Mario Heiderich, Cure53. Licensed under Apache-2.0 OR MPL-2.0.
• css/hjs-dark.min.css, css/hjs-light.min.css, js/highlight.min.js (highlight.js): Copyright © 2006 Ivan Sagalaev. Licensed under a BSD-3-Clause License.
• icons/check.svg, icons/clipboard.svg, icons/chevron-left.svg, icons/chevron-right.svg (entypo): Copyright © Daniel Bruce. Licensed under a CC BY-SA 4.0 license.