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:

Newsletter System

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"

Creating a Newsletter Page

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:

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

Technology Stack

Repository

github.com/johnsosoka/jscom-ice