name

jekyll-research-theme

description

Create production-grade, accessible Jekyll themes for researchers conducting "research in public." Generates complete lab notebook-style themes with Tufte-inspired sidenotes, KaTeX math rendering, and WCAG 2.1 AA compliance. Use when building Jekyll themes for scientific journals, experiment logs, field notes, or research documentation sites. Supports collections for organizing experiments and field notes, responsive sidenote rendering (sidebar on desktop, inline on mobile), and full-width layout options.

Jekyll Research Log Theme Generator

Generate a complete, production-ready Jekyll theme designed for researchers who work in public. The theme prioritizes accessibility, elegant typography, and scientific workflows with Tufte-style sidenotes and math rendering.

Design Philosophy

Create a lab notebook aesthetic that feels like a refined scientist's journal:

Typography-first: Serif display fonts paired with readable body text
Breathing room: Generous whitespace and margins for sidenotes
Accessibility-first: WCAG 2.1 AA compliant by default
Responsive sidenotes: Desktop sidebar positioning, mobile inline rendering
Math-ready: KaTeX integration for equations and formulas

Theme Structure

Generate a complete Jekyll theme with this directory structure:

theme-name/
├── _layouts/
│   ├── default.html
│   ├── experiment.html
│   ├── field-note.html
│   └── home.html
├── _includes/
│   ├── head.html
│   ├── header.html
│   ├── footer.html
│   ├── sidenote.html
│   └── math.html
├── _sass/
│   ├── _base.scss
│   ├── _typography.scss
│   ├── _layout.scss
│   ├── _sidenotes.scss
│   ├── _accessibility.scss
│   └── main.scss
├── assets/
│   ├── css/
│   │   └── main.scss
│   └── js/
│       └── sidenotes.js
├── _config.yml
├── index.html
└── README.md

Core Features Implementation

1. Collections Configuration

In _config.yml, define collections for content types:

collections:
  experiments:
    output: true
    permalink: /experiments/:title/
  field_notes:
    output: true
    permalink: /notes/:title/

defaults:
  - scope:
      path: ""
      type: "experiments"
    values:
      layout: "experiment"
      full_width: false
  - scope:
      path: ""
      type: "field_notes"
    values:
      layout: "field-note"
      full_width: false

2. Tufte-Style Sidenotes

Implement responsive sidenotes that adapt to viewport:

HTML Pattern (_includes/sidenote.html):

<label for="sn-{{ include.id }}" class="margin-toggle sidenote-number"></label>
<input type="checkbox" id="sn-{{ include.id }}" class="margin-toggle"/>
<span class="sidenote">{{ include.content }}</span>

CSS Requirements (_sass/_sidenotes.scss):

Desktop (>768px): Position sidenotes in right margin (float or CSS Grid)
Mobile (≤768px): Hide margin-toggle checkbox, display sidenotes inline after reference
Ensure .sidenote-number has proper ARIA labels for screen readers
Use counter-reset and counter-increment for automatic numbering

JavaScript Enhancement (assets/js/sidenotes.js):

Progressive enhancement for keyboard navigation
Ensure sidenotes are accessible via Tab key
Add ARIA attributes dynamically if needed

3. Full-Width Layout Support

In layout files, check for full_width frontmatter:

{% if page.full_width %}
  <article class="content-full-width">
{% else %}
  <article class="content-sidenotes">
{% endif %}

CSS handles width constraints:

.content-sidenotes {
  max-width: 55%;  // Leaves room for sidenotes
}

.content-full-width {
  max-width: 90%;  // Full reading width
}

4. KaTeX Math Rendering

In _includes/math.html:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    renderMathInElement(document.body, {
      delimiters: [
        {left: "$$", right: "$$", display: true},
        {left: "$", right: "$", display: false}
      ]
    });
  });
</script>

Include in <head> of layouts that need math support.

5. Experiment Layout

_layouts/experiment.html should include:

Title and metadata (date, tags, status)
Hypothesis section
Methodology section
Results/observations section
Sidenote support throughout
Tag display with links to filtered views

6. Field Note Layout

_layouts/field-note.html should include:

Timestamp
Quick-capture formatting (less structured than experiments)
Tag support
Sidenote support
Optional linking to related experiments

Accessibility Requirements

Semantic HTML

Use proper heading hierarchy (h1 → h2 → h3)
<main>, <nav>, <article>, <aside> for structure
<figure> and <figcaption> for images and diagrams

WCAG 2.1 AA Compliance

Color Contrast: Minimum 4.5:1 for normal text, 3:1 for large text
Keyboard Navigation: All interactive elements accessible via keyboard
Focus Indicators: Visible focus states on all focusable elements
Skip Links: "Skip to main content" link at top of page
Alt Text: All images require alt attributes (enforce in layouts)

ARIA Attributes

aria-label for icon buttons
aria-current="page" for current navigation item
role="navigation" for nav elements
aria-describedby for sidenote references

Screen Reader Optimization

Sidenote numbers should have screen reader text: "sidenote reference"
Hidden content should use aria-hidden="true" or .visually-hidden class
Tables need proper <caption> and header markup

Typography Guidelines

Font Pairing

Choose distinctive, characterful fonts:

Headings: Serif display font (e.g., Playfair Display, Cormorant Garamond, Crimson Pro)
Body: Readable serif (e.g., Lora, Spectral, Source Serif Pro)
Monospace: For code blocks (e.g., JetBrains Mono, Fira Code)

Type Scale

Use modular scale for hierarchy:

$base-font-size: 18px;
$scale-ratio: 1.25; // Major third

h1: $base-font-size * $scale-ratio * $scale-ratio * $scale-ratio;
h2: $base-font-size * $scale-ratio * $scale-ratio;
h3: $base-font-size * $scale-ratio;
body: $base-font-size;
small: $base-font-size / $scale-ratio;

Line Height

Body text: 1.6-1.8 for readability
Headings: 1.2-1.3 for tighter spacing
Code blocks: 1.5 for clarity

Visual Design

Color Palette

Lab notebook aesthetic with muted, sophisticated tones:

Background: Off-white or warm cream (#FAFAF8, #F5F5F0)
Text: Deep charcoal or near-black (#1A1A1A, #2C2C2C)
Accent: Muted scientific tones (deep teal, rust, indigo)
Borders: Subtle gray for separation (#D4D4D4)

Layout Principles

Asymmetry: Sidenotes create natural asymmetry
Generous margins: 10-15% on sides for breathing room
Vertical rhythm: Consistent spacing using modular scale
Grid system: Use CSS Grid for layout structure

Decorative Elements

Thin horizontal rules (1px) to separate sections
Subtle drop caps for experiment introductions (optional)
Figure numbering in margins
Date stamps styled like lab notebook entries

Tagging System

Implementation

In _config.yml:

tag_page_layout: tag
tag_page_dir: tags

Create tags/index.html to list all tags.

For each tag, generate filtered collections view:

{% for post in site.experiments %}
  {% if post.tags contains page.tag %}
    <!-- Display post -->
  {% endif %}
{% endfor %}

Display Pattern

Tags appear below post title as clickable pills
Tag pages show chronological list of related content
Support multiple tags per entry (project, subject, methodology)

Configuration File

Provide sensible defaults in _config.yml:

title: Research Log
description: Public research and experimentation journal
author: [Your Name]
url: https://example.com
baseurl: ""

# Theme settings
sidenotes: true
math_rendering: true
font_headings: "Crimson Pro"
font_body: "Lora"

# Accessibility
skip_to_content: true
high_contrast_mode: false

# Collections (defined above)

# Defaults (defined above)

# Build settings
markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge

README Documentation

Include comprehensive README with:

Installation instructions
Configuration options
How to create experiments vs field notes
Sidenote syntax examples
Math rendering examples (inline $x$ and display $$x$$)
Full-width layout usage
Accessibility features
Customization guide

Example Content Templates

Experiment Frontmatter

---
layout: experiment
title: "Hypothesis Testing: Neural Network Convergence"
date: 2024-01-15
tags: [machine-learning, optimization, neural-networks]
status: ongoing
full_width: false
---

Field Note Frontmatter

---
layout: field-note
title: "Initial Observations on Dataset Bias"
date: 2024-01-15T14:30:00
tags: [data-quality, machine-learning]
related_experiment: neural-network-convergence
---

Build Instructions

Generate all files in the directory structure outlined above
Implement responsive sidenotes with mobile-first approach
Include KaTeX CDN links in head for math rendering
Ensure all color combinations pass WCAG AA contrast requirements
Test keyboard navigation on all interactive elements
Validate HTML semantics and ARIA usage
Create example content (2 experiments, 3 field notes) to demonstrate features

Design Constraints

No JavaScript dependencies beyond KaTeX and sidenote enhancements
No Jekyll plugins (GitHub Pages compatible)
Mobile-first responsive design
Graceful degradation if JavaScript disabled
Print stylesheet for archival (sidenotes inline, good page breaks)

Quality Checklist

Before considering the theme complete, verify:

Sidenotes render correctly on desktop (margin) and mobile (inline)
Math equations display properly with KaTeX
All color contrasts pass WCAG AA (check color contrast linter instuctions below)
Keyboard navigation works for all interactive elements
Focus indicators are clearly visible
Collections generate proper permalinks
Tags link to filtered views
Full-width layout disables sidenotes appropriately
Typography scales harmoniously across devices
Code blocks have proper syntax highlighting
Example content demonstrates all features

color contrast linter checking

Installation

Install the package via pip:

pip install color-contrast-linter

Usage

1. Initialize Configuration

Start by creating a configuration file. Run the init command to generate a .color_pairs.yml file in your project root:

cc-lint init

This file allows you to define the minimum contrast standard (AA or AAA) and list the color pairs you want to test.

Example .color_pairs.yml:

min_contrast: AA
pairs:
  - foreground: "#000000"
    background: "#ffffff"
  - foreground: "#767676" # Might fail AA for normal text
    background: "#ffffff"

2. Run the Linter

Execute the lint command to check your configured color pairs for accessibility issues:

cc-lint lint

The tool will analyze each pair and report:

Pass/Fail status based on your min_contrast setting.
Actual contrast ratio (e.g., 21.0:1).
WCAG Level achieved (AA, AAA, or Fail).

Notes

This theme prioritizes researchers who think in experiments and observations. Every design decision should support scientific workflows: hypothesis documentation, iterative refinement, cross-referencing notes, and mathematical notation. The aesthetic should feel like a well-maintained lab notebook—professional, organized, and inviting for long-form reading.

Install Skill

SKILL.md