Type on Strap: a Jekyll theme that ships its own build tooling

What the theme actually includes

Type on Strap is described as a feature-rich Jekyll theme for writers, developers and creatives, with portfolio, gallery, dark mode, search, KaTeX and Mermaid out of the box. The feature list is more specific than the usual theme marketing. There is responsive design across devices, portfolio and gallery pages for projects, an automatic light and dark theme with a manual toggle, full-text search through a separate project called Simple-Jekyll-Search, native equation writing with KaTeX, native diagram rendering with Mermaid, multiple comment systems (Disqus, Giscus, Utterances and Cusdis), Bootstrap compatibility for responsive and customisable layouts, SEO support through jekyll-seo-tag, syntax highlighting with customisable Base16 themes, and built-in tags, categories, an archive and pagination. The theme is published as a Ruby gem as well, and the demo site is at the project homepage.

Three ways to install it

The easiest route is as a remote theme with GitHub Pages, which means one line in your configuration file.

remote_theme: sylhare/Type-on-Strap

If you want your own copy, you fork and clone the repository, install Ruby and Bundler, install the theme's dependencies with bundle install, customise the theme, and run the Jekyll server with bundle exec jekyll serve. There is a third route as a Ruby gem, which the README links to a separate tutorial. The choice between the remote theme and the gem is the usual one for Jekyll: the remote theme gives you a site you cannot easily modify, while the gem gives you the source. The repository also ships a Gemfile and a gemspec, which is what makes the gem route possible, and the Docker badge in the README points to a published image for the theme.

The directory layout is where the features live

The structure section lists the main files, and it is a good map of what the theme does. There are includes for the theme includes, layouts for the theme layouts, a portfolio collection for articles used on the portfolio page, posts for blog posts, and a Sass directory whose partials are compiled into CSS at runtime. The assets directory holds the JavaScript and CSS compiled for distribution alongside their raw sources, a fonts directory with Font-Awesome and other fonts, and an images directory. The pages directory holds the standalone pages: a 404 page for a wrong URL, about, archive, categories, gallery, portfolio, search and tags. The data directory is where the configuration fragments live, with files for authors, comments, icons, an icon set builder, language localisation, the navigation menu, a bibliography reference and social sharing settings. The index.html at the root is the sample home page with blog pagination.

Configuration is one YAML file with a disable convention

The configuration section opens with an instruction and a rule that is unusual enough to be worth quoting exactly. Open _config.yml in a text editor to change most of the blog's settings, and if a variable in that document is marked as optional, you disable the feature by removing all text from the variable. That convention means there is no boolean switch to flip, which is a small thing that makes the configuration file easy to read at a glance: a variable with a value is on, a variable with nothing is off.

title: My Jekyll Blog                 # Name of website
avatar: assets/img/avatar.png         # Path of avatar image, to be displayed in the theme's header
description: My blog posts            # Short description, primarily used by search engines
favicon: assets/favicon.ico           # Icon displayed in the tab
color_theme: auto                     # color theme auto, dark or light

The meta variables are described as basic information used throughout the site and as meta properties for search engines, browsers and the site's RSS feed. The colour theme can be set to dark or light in the Sass variables file, and choosing auto gives a small icon in the navbar for switching manually.

Base URL, pagination and the plugin list

Two configuration shapes are documented, and picking the wrong one is the classic Jekyll deployment mistake. A site without a baseurl, such as a GitHub Pages site whose repository name is the username, uses an empty baseurl and the GitHub Pages URL. A site with a baseurl, like the Type on Strap demo in a sub-directory, sets the baseurl to the sub-directory path with the same host.

baseurl: "/sub-directory"
url: "https://username.github.io"

The blog configuration section then covers the parts the theme expects.

# BLOG CONFIGURATION
post_navigation: true
paginate: 10
paginate_path: "blog/page:num"
plugins: [jekyll-paginate, jekyll-seo-tag, jekyll-feed]

Those three plugins are the ones GitHub Pages validates, which is why the list is short rather than exhaustive: on GitHub Pages you can only use the plugins the platform allows, and a theme that needs more would break for the majority of its users.

A TypeScript CLI that manages the theme's own assets

The package manifest describes something most blog themes do not have: a command line tool for the theme, run with tsx, living under a .github/cli directory in the repository. The scripts cover posting, image compression and thumbnail and webp generation, building the JavaScript, cutting a release, and updating the vendored KaTeX, Mermaid and search index. There are validators for KaTeX, Mermaid, Font-Awesome and search, and separate test projects for unit, browser, integration and end-to-end runs, with the end-to-end suite driven by Playwright. The image scripts are the reason this exists: a theme that ships screenshots, avatars and portfolio images needs those assets compressed and converted to modern formats, and doing that by hand every time a post lands is exactly the chore a script should take.

The update scripts are the part that ages worst

Three of the scripts exist to refresh vendored third-party assets: update:katex, update:mermaid and update:search, each pointing at a file under an update directory. Vendoring is the right call for a theme distributed through RubyGems and GitHub Pages, because you cannot rely on a CDN at build time and you cannot rely on a plugin being present. The cost is that the vendored copies drift from upstream, and on a theme with a long life the pinned KaTeX and Mermaid versions are the versions most likely to be behind. The validators are the mitigation: validate:katex, validate:mermaid, validate:fa and validate:search each check the vendored copy against what the theme expects. A theme that ships the checks as well as the updates is doing the right thing, but the fact that the checks exist at all tells you how often they fail.

Where Type on Strap is the wrong choice

Four limits apply. It is a Jekyll theme, so it inherits the whole Jekyll dependency model, with a Gemfile to install and a Ruby toolchain to keep working, and the plugin list is constrained by what GitHub Pages allows rather than by what the theme could use. It ships a substantial amount of JavaScript tooling for what is ultimately a blog, so a team that does not want Node in the build will have to think about that. The search implementation is a separate project by the same author, which means the search index is a build artefact you have to regenerate and keep in step with your content. And the theme's breadth is a maintenance liability rather than an asset if you use two of the fourteen features: portfolio, gallery, search, maths, diagrams, four comment systems, dark mode and the rest are all code you inherit and eventually maintain, and the theme does not document a way to remove them without editing the layouts.

Editorial conclusion

Use Type on Strap when you want a Jekyll site with search, dark mode, maths and diagrams already working rather than assembled from plugins, because those are the features most themes leave you to wire up. Do not expect a plain theme drop-in, since the theme ships a TypeScript CLI that manages its own assets and dependency versions. Verify first that you can run the CLI, since the scripts are invoked with tsx and the project expects a Node toolchain, that the search index and the KaTeX and Mermaid versions are updated to your needs, since those are checked in as vendored assets, and whether the remote theme route is enough for you, because the Ruby gem route is what gives you control over the configuration.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. sylhare/Type-on-Strap on GitHub