# Type on Strap: a Jekyll theme that ships its own build tooling > Type on Strap is a Jekyll theme for writers and developers with portfolio, gallery, search, dark mode, KaTeX and Mermaid built in, and it is published both as a remote theme and as a Ruby gem. The interesting part is the tooling underneath: a TypeScript CLI in the repository handles image compression, dependency updates and validation, which is more machinery than a typical blog theme carries. **sylhare/Type-on-Strap** — 🎨 Simplistic, responsive jekyll based open source theme - Repository: https://github.com/sylhare/Type-on-Strap - Website: https://sylhare.github.io/Type-on-Strap/ - Stars: 855 · Forks: 920 - Language: Liquid - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/sylhare-type-on-strap ## 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. ```yml 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. ```yml 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. ```yml baseurl: "/sub-directory" url: "https://username.github.io" ``` The blog configuration section then covers the parts the theme expects. ```yaml # 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. ## 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. ## FAQ ### How do I use Type on Strap as a GitHub Pages remote theme? Add one line to your _config.yml with remote_theme: sylhare/Type-on-Strap. For a local copy, fork and clone the repository, install Ruby and Bundler, run bundle install, customise the theme and start the server with bundle exec jekyll serve. There is also a Ruby gem route with its own tutorial. ### What features does the Type on Strap Jekyll theme include? Portfolio and gallery pages, an automatic light and dark theme with a manual toggle, full-text search through Simple-Jekyll-Search, KaTeX for equations, Mermaid for diagrams, four comment systems, Bootstrap compatibility, SEO through jekyll-seo-tag, Base16 syntax highlighting themes, and built-in tags, categories, an archive and pagination. ### How do I turn a Type on Strap feature off? The README explains that if a configuration variable is marked as optional, you disable the feature by removing all text from that variable in _config.yml, rather than by setting a flag to false. ### What is the type-on-strap-helper npm package for? It holds the CLI utilities for the theme, run with tsx: posting, image compression, thumbnail and webp generation, building the JavaScript, cutting a release, updating the vendored KaTeX, Mermaid and search index, and validating each of those. The package also configures Jest projects for unit, browser and integration tests and a Playwright end-to-end suite. ### Which GitHub Pages plugins does Type on Strap rely on? The blog configuration section lists jekyll-paginate, jekyll-seo-tag and jekyll-feed, with the README noting that those plugins are the ones validated by GitHub Pages, which is why the list is limited. ## Sources - [License: MIT](https://github.com/sylhare/Type-on-Strap/blob/master/LICENSE) - [Project website](https://sylhare.github.io/Type-on-Strap/) - [README](https://github.com/sylhare/Type-on-Strap/blob/master/README.md) - [Releases](https://github.com/sylhare/Type-on-Strap/releases) - [sylhare/Type-on-Strap on GitHub](https://github.com/sylhare/Type-on-Strap) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sylhare-type-on-strap