jscom-ice

Jekyll theme for johnsosoka.com

jscom-ice

Overview

jscom-ice is a custom Jekyll theme built specifically for johnsosoka.com. It’s a dark-themed, minimalist blog theme designed for technical writing and personal publishing. The theme is open source and published as a Ruby gem, though it’s primarily tailored for personal use.

The theme emphasizes readability with a carefully crafted typography system using IBM Plex Sans for body text and JetBrains Mono for code blocks. It features a responsive design with both light and dark color schemes, though the dark theme is the primary aesthetic.

Features

Core Layouts

The theme provides five primary layouts:

default — Base layout with common HTML structure, head, and scripts
home — Landing page layout for the site’s homepage
page — Standard content pages
post — Blog posts with navigation, tags, and author information
lore — Specialized layout for storytelling or narrative content

Reusable Components

The theme includes 15+ reusable includes for common UI patterns:

Component	Purpose
`navbar.html`	Responsive navigation with mobile hamburger menu
`footer.html`	Site footer with links and newsletter signup
`posts.html`	Blog post listing with excerpts
`post_navigation.html`	Previous/next post navigation
`tags.html`	Tag cloud and post categorization
`carousel.html`	Image carousel for galleries
`image-modal.html`	Lightbox-style image viewer
`contact-me-form.html`	Contact form with validation
`embed-audio.html`	Audio player embed
`yearly_content.html`	Archive organization by year

A complete newsletter subscription system with three components:

Footer signup — Compact horizontal form for site-wide signup
Subscribe form — Full subscription form with name/email fields
Unsubscribe form — Email-based unsubscription
Status check — Subscription status lookup with formatted results

The newsletter components integrate with a REST API and display Bootstrap-styled alerts for user feedback.

Styling Architecture

The theme uses a modular SCSS architecture organized into:

_sass/
├── main.scss              # Entry point with variables
├── base/
│   └── _base.scss         # Reset and base styles
├── layout/
│   ├── _layout.scss       # Grid and structural styles
│   └── _footer.scss       # Footer-specific styles
├── pages/
│   ├── _page.scss         # Standard page styles
│   ├── _post.scss         # Blog post styles
│   └── _home.scss         # Homepage styles
└── component/
    ├── _all-components.scss    # Component manifest
    ├── _navbar.scss            # Navigation styles
    ├── _posts.scss             # Post listing styles
    ├── _newsletter.scss        # Newsletter form styles
    ├── _contact.scss           # Contact form styles
    ├── _form.scss              # Form element styles
    ├── _code.scss              # Inline code styles
    ├── _codeblock.scss         # Code block styling
    ├── _highlight.scss         # Syntax highlighting
    ├── _carousel.scss          # Image carousel
    ├── _author.scss            # Author bio component
    ├── _table.scss             # Table styles
    ├── _image-modal.scss       # Lightbox modal
    ├── _post-navigation.scss   # Post pagination
    └── _github-gist.scss       # GitHub Gist embedding

Typography System

Base font: IBM Plex Sans (18px base size)
Code font: JetBrains Mono
Modular scale: 1.25 ratio for consistent sizing
Line height: 1.6 for body text, 1.3 for headings

Color Palette

Dark Theme (Primary):

Background: #131418 (dark-black)
Text: #c7bebe (dark-text-base-color)
Links: #84a5ff (dark-text-link-blue)
Accent: #5b9cff (accent-blue)

Light Theme:

Background: #fff
Text: #434648
Links: #003fff

Frontend Dependencies

Bootstrap 5 — CSS framework and JavaScript components
jQuery 3.7 — DOM manipulation and event handling
Popper.js — Positioning engine for dropdowns and tooltips
Custom JS — Navbar toggle, image modal, newsletter forms

Usage

Installation

Add to your Jekyll site’s Gemfile:

group :jekyll_plugins do
  gem "jscom_ice", '~> 1.0.1'
end

Add to _config.yml:

theme: jscom_ice

Run Bundler:

bundle install

Configuration

Enable footer newsletter signup in _config.yml:

newsletter:
  api:
    url: https://api.example.com/v1/newsletter
  footer:
    enabled: true
    title: "Newsletter Signup"
    description: "Get updates delivered to your inbox"

Create newsletter.md:

---
layout: page
title: Newsletter
permalink: /newsletter/
---

<div class="newsletter-page-container">
  {% include newsletter-subscribe-form.html %}
  {% include newsletter-unsubscribe-form.html %}
  {% include newsletter-status-check.html %}
</div>

Gem Release

The theme is published to RubyGems. To release a new version:

Update version in jscom_ice_theme.gemspec
Build the gem: gem build jscom_ice_theme.gemspec
Push to RubyGems: gem push jscom_ice-{version}.gem

Technology Stack

Component	Technology
Static Site Generator	Jekyll 4.3+
Language	Ruby
Styling	SCSS with modular architecture
CSS Framework	Bootstrap 5
JavaScript	jQuery 3.7, vanilla JS
Package Distribution	RubyGems
License	GPL-3.0

Repository

github.com/johnsosoka/jscom-ice