jekyll-calconnect

Table of Contents

• Purpose
• Features
• Installation
• Configuration
  • Basic Configuration
  • Theme Options
  • Header Navigation
• Layouts
• Page Front Matter
• Content Formats
  • Markdown
  • AsciiDoc
• Overriding Components
  • Layout Override
  • Component Override
  • CSS Override
• Dark Mode
  • Detection Script
  • CSS Classes
• Logo Files
  • Available Logos
  • Copying Logos
• Vite + Tailwind CSS (Optional)
  • Enable Vite
  • Install Dependencies
  • Development
• Development
• License

A Jekyll theme gem for CalConnect documentation sites. Provides semantic HTML layouts, AsciiDoc and Markdown content support, and optional Vite + Tailwind CSS integration.

Purpose

The jekyll-calconnect theme provides a shared design system for all CalConnect documentation sites, ensuring consistent branding, navigation, and user experience across calconnect.org, devguide.calconnect.org, and future CalConnect sites.

Features

• Semantic HTML - Clean, accessible markup with BEM class naming

• Dark Mode - Built-in theme toggle with system preference detection

• AsciiDoc & Markdown - Full support for both content formats

• Responsive Design - Mobile-first approach with sidebar navigation

• Tailwind CSS 4 - Optional integration for modern styling

• Extensible - Override any component in your site

Installation

Add this line to your Jekyll site’s Gemfile:

gem "jekyll-calconnect", "~> 1.0"

And add this line to your Jekyll site’s _config.yml:

theme: jekyll-calconnect

Then execute:

bundle install

Or install it yourself as:

gem install jekyll-calconnect

Configuration

Basic Configuration

# _config.yml
theme: jekyll-calconnect

collections:
  pages:
    output: true
    permalink: /:path/
  appendixes:
    output: true
    permalink: /Appendix/:path/

calconnect:
  logo: /assets/images/logo-purple.svg
  logo_dark: /assets/images/logo-white.svg
  organization_name: CalConnect
  dark_mode: true

Theme Options

Option	Default	Description
logo	/assets/images/logo-purple.svg	Path to light mode logo
logo_dark	/assets/images/logo-white.svg	Path to dark mode logo
organization_name	CalConnect	Organization name for copyright
dark_mode	true	Enable dark mode toggle
navigation.header_links	[]	Array of navigation links
cta_url	nil	Call-to-action button URL
cta_text	nil	Call-to-action button text

Header Navigation

calconnect:
  navigation:
    header_links:
      - title: "About"
        url: "/about/"
      - title: "Membership"
        url: "/membership/"
      - title: "Events"
        url: "/events/"

Layouts

Layout	Description
base	Base HTML structure with head, header, footer (internal use)
default	Documentation page with sidebar navigation
home	Homepage layout with hero section
page	Simple content wrapper without sidebar
toc	Table of Contents page with recursive listing
appendix	Appendix content with sidebar navigation

Page Front Matter

---
layout: default
title: Page Title
parent: "/ParentPath"        # Parent page path for navigation
mainParent: "SectionName"    # Top-level section name for sidebar
parents: "Name:/path;Name2:/path2"  # Breadcrumb chain
order: 400                   # Sort order in navigation
---

Content Formats

The theme supports both Markdown and AsciiDoc content formats.

Markdown

---
layout: default
title: Getting Started
---

# Getting Started

Content here with standard Markdown syntax.

AsciiDoc

---
layout: default
title: Getting Started
---

= Getting Started

:toc: left

Content here with AsciiDoc syntax.

Add jekyll-asciidoc to your Gemfile for AsciiDoc support:

group :jekyll_plugins do
  gem "jekyll-asciidoc"
end

Overriding Components

Sites can override any theme file by creating a local version.

Layout Override

your-site/
├── _layouts/
│   └── default.html       # Overrides theme's default.html

Component Override

your-site/
├── _includes/
│   └── components/
│       └── header.html    # Overrides theme's header.html

CSS Override

your-site/
└── _sass/
    └── calconnect/
        └── _variables.scss  # Override design tokens

Dark Mode

The theme supports dark mode via the html.dark class on the <html> element.

Detection Script

The theme automatically detects system preference and localStorage setting:

if (localStorage.theme === 'dark' ||
    (!('theme' in localStorage) &&
     window.matchMedia('(prefers-color-scheme: dark)').matches)) {
  document.documentElement.classList.add('dark')
}

CSS Classes

Use these classes for dark mode styling:

• dark:hidden - Hidden in dark mode

• dark:block - Visible only in dark mode

• dark:bg-gray-950 - Dark background color

• dark:text-white - White text in dark mode

Logo Files

Logo files must be copied from calconnect.org to ensure consistency.

Available Logos

File	Purpose	Size
logo-purple.svg	Light mode logo	~857 bytes
logo-white.svg	Dark mode logo	~854 bytes
logo-full-purple.svg	Full logo with text (light)	~3149 bytes
logo-full-white.svg	Full logo with text (dark)	~3143 bytes

Copying Logos

# From calconnect.org repository
cp calconnect.org/assets/images/logo-*.svg your-site/assets/images/

Vite + Tailwind CSS (Optional)

The theme can use Vite for Tailwind CSS processing.

Enable Vite

calconnect:
  use_vite: true
  vite:
    port: 3036

Install Dependencies

npm install

Development

npm run dev    # Start Vite dev server
npm run build  # Build for production

Development

To set up your environment to develop this theme:

# Clone the repository
git clone https://github.com/calconnect/jekyll-calconnect.git
cd jekyll-calconnect

# Install Ruby dependencies
bundle install

# Install Node.js dependencies (for Vite/Tailwind)
npm install

# Run the example site
cd example
bundle exec jekyll serve

The theme is setup just like a regular Jekyll site. To test modifications, make changes to the files in _layouts/, _includes/, or _sass/ and preview the changes in the example site.

License

The theme is available as open source under the terms of the MIT License.