Claude-skill-registry jekyll-research-theme

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.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/jekyll-research-theme" ~/.claude/skills/majiayu000-claude-skill-registry-jekyll-research-theme && rm -rf "$T"

manifest: skills/data/jekyll-research-theme/SKILL.md

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

_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

_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

_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:

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

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.