CB-Essay Documentation, Frankenstein; or, the modern prometheus

Overview

CB-Essay is a Jekyll-based framework that extends CollectionBuilder-CSV to combine long-form essay writing with digital collection features. Write in Markdown, integrate primary sources, and publish multimodal scholarly work on the web for free.

What Makes CB-Essay Different?

Traditional digital publishing treats essays and collections separately. CB-Essay unifies them through a dual-collection model:

Essay Collection (_essay/ directory) - Your narrative content as Markdown files with sequential navigation
Object Collection (CSV metadata) - Digital items you can reference within essays using simple includes

This allows you to write with, on, and for the web - integrating archival materials, images, maps, and multimedia directly into your scholarly narratives.

Perfect For

Digital humanists creating annotated editions
Historians presenting narratives alongside primary sources
Educators building interactive course readers
Archivists providing context around collections
Writers publishing long-form digital scholarship

Quick Start

1. Get the Template

Visit github.com/CollectionBuilder/cb-essay and click “Use this template” → “Create a new repository”.

2. Enable GitHub Pages

Go to Settings → Pages
Under Source, select GitHub Actions
GitHub will display a Jekyll workflow option - click Configure
In the workflow file that opens, find line 40 where it says ruby-version: '3.1'
Change the version from 3.1 to 3.4
Click Commit changes

Your site will be live at https://username.github.io/repository-name in a few minutes.

3. Create Your First Essay

Navigate to the _essay/ folder in your repository
Click “Add file” → “Create new file”
Name it my-first-essay.md
Add this content:

---
title: My First Essay
order: 1
---

## Introduction

This is my first essay using CB-Essay! I can write in **Markdown** and include [links](https://example.com).

### Adding Features

I can add blockquotes:

{% include essay/feature/blockquote.html
   quote="Knowledge comes, but wisdom lingers"
   speaker="Alfred Lord Tennyson" %}

And margin notes:{% include essay/feature/aside.html text="This is a margin note!" %}

Commit changes and wait for GitHub Pages to rebuild (2-3 minutes)

That’s it! Your essay is live.

Essay Writing

File Structure

All essays live in the _essay/ directory:

your-project/
├── _essay/
│   ├── 01-introduction.md
│   ├── 02-chapter-one.md
│   └── 03-conclusion.md

Required Front Matter

Every essay needs YAML front matter:

---
title: Your Essay Title
order: 1
---

title: Appears in navigation and page header
order: Controls display sequence (1, 2, 3…)

Optional Front Matter

---
title: Of Thumbs
order: 1
byline: Michel de Montaigne
featured-image: /assets/img/chapter-image.jpg
---

byline: Author attribution
featured-image: Header image for this essay

Essays automatically get prev/next navigation based on order. Use gaps (1, 10, 20, 30) to allow easy insertion later.

Workflow

Browser-based (recommended):

Edit directly on GitHub.com
Use GitHub.dev (press . in your repository)
Use Codespaces for full development environment

Local development: Follow the CollectionBuilder-CSV setup guide for local Jekyll installation.

For detailed guidance, see Essay Writing Guide.

Essay Features

When to use this section: After you’ve created your first essay and want to add blockquotes, margin notes, or other specialized features.

CB-Essay provides specialized includes for scholarly writing. Copy the examples below directly into your essays. For complete examples and best practices, see the Writing Features essay.

Blockquotes

Styled quotations with attribution and source links.

Basic blockquote:

{% include essay/feature/blockquote.html
   quote="Knowledge comes, but wisdom lingers"
   speaker="Alfred Lord Tennyson" %}

With source:

{% include essay/feature/blockquote.html
   quote="It is a truth universally acknowledged..."
   speaker="Jane Austen"
   source="Pride and Prejudice" %}

Large centered quote:

{% include essay/feature/blockquote.html
   quote="The only way out is through"
   size="xl"
   align="center" %}

Parameters:

quote - Quote text (required)
speaker - Person quoted
source - Title of source work
source-link - URL to source
size - sm, md, lg, xl, xxl
align - left, center, right

Asides (Margin Notes)

Margin notes appear beside text on desktop, inline on mobile.

Text-only aside:

Here's text with a margin note.{% include essay/feature/aside.html text="This is a margin note!" %} Text continues.

Aside with collection item:

{% include essay/feature/aside.html
   objectid="demo_001"
   text="Context about this item" %}

Parameters:

text - Margin note text (supports Markdown)
objectid - Collection item ID from your metadata CSV
caption - Override item title
height - Max height (default: 205px)
gallery - Link to viewer (true) or item page (false)

Image Galleries

Display multiple collection items:

{% include feature/gallery.html
   heading="Items after 1900"
   filter="item.format contains 'image'" %}

Mini Maps

Embed maps at specific coordinates:

{% include feature/mini-map.html
   latitude="46.727485"
   longitude="-117.014185"
   zoom="10" %}

Parameters:

latitude - Center latitude (required)
longitude - Center longitude (required)
zoom - Zoom level 1-18 (default: 10)
height - Map height (CSS value)

Section Breaks

Create visual breaks with scroll transitions:

{% include essay/new-section.html %}

## New Section Title

Content continues...

Complete Feature Reference

For all parameters and advanced usage, see:

Essay Features Reference
Demo essays with live examples

Collection Integration

When to use this section: When you want to add images, PDFs, audio, or other collection items to your essays.

This section covers the basics of referencing collection items in essays. For a complete tutorial with examples, see the Collection Integration essay.

Using Collection Items

Reference items from your metadata CSV using their objectid:

{% include essay/feature/aside.html
   objectid="demo_001"
   text="This manuscript shows early revisions" %}

Metadata Requirements

Items must exist in your _data/[metadata].csv file with:

objectid - Unique identifier
title - Item title
format - Item type (image, pdf, video, etc.)
image_small, image_thumb - For images

CollectionBuilder Features in Essays

All standard CollectionBuilder includes work in essays:

Item card:

{% include feature/item-card.html objectid="demo_001" %}

Timeline:

{% include feature/timeline.html %}

Subject cloud:

{% include feature/cloud.html fields="subject" %}

For complete CollectionBuilder documentation, see CollectionBuilder Docs.

Theme Options

When to use this section: To customize your site’s colors, fonts, navigation, and homepage layout.

Configure all theme options in _data/theme.yml:

Homepage Image Options

Full image:

image-style: full-image
featured-image: /assets/img/banner.jpg
home-banner-image-position: center

Half image:

image-style: half-image
featured-image: /assets/img/cover.jpg

No image:

image-style: no-image

show-contents-nav: true    # "Contents" button in navbar opens chapter list panel
show-homepage-toc: true    # chapter table of contents on the homepage
show-section-nav: false    # floating sidebar TOC built from H2s on each essay page

Common configurations:

Simple essay (single narrative, minimal nav):

show-contents-nav: false
show-homepage-toc: false
show-section-nav: false

Multi-chapter monograph:

show-contents-nav: true
show-homepage-toc: true
show-section-nav: false

Long single essay with in-page navigation:

show-contents-nav: false
show-homepage-toc: false
show-section-nav: true

Color Themes

CB-Essay includes 8 built-in color themes inspired by historical printing presses, each designed for accessibility and long-form reading:

color-theme: aldine  # default, idaho, lyre, nonesuch, aldine, doves, kelmscott, gregynog, ashendene

Built-in themes:

default - Warm cream neutral
idaho - Douglas-fir green
lyre - Faded indigo
nonesuch - Cream with red accents (light navbar)
aldine - Marine blue
doves - Severe black-on-white
kelmscott - Holland blue with red (light navbar)
gregynog - Slate buckram grey-blue
ashendene - Faded brown

Each theme provides coordinated colors for navbar, links, accents, and UI elements.

Custom color:

color-theme: custom
custom-color: "#8B4513"
navbar-style: dark  # dark or light

The system automatically generates an accessible color palette from your hex color.

Typography & Fonts

CB-Essay offers three font options:

1. Theme fonts (easiest) - Automatically matched to your color theme:

base-font-family: theme
display-font-family: theme

2. Georgia (no CDN) - Works offline, no external requests:

base-font-family: Georgia
display-font-family: Georgia

3. Custom Google Font:

base-font-family: "'Literata', Georgia, serif"
display-font-family: "'Literata', Georgia, serif"
font-cdn: "https://fonts.googleapis.com/css2?family=Literata:ital,opsz,wght@0,7..72,400;0,7..72,500;1,7..72,400&display=swap"

You can mix options - for example, use theme fonts for body text with a custom display font for headings.

Font size:

base-font-size: 1.2em  # 1.2em - 1.4em recommended for long-form reading

Creating Your Own Theme

CB-Essay includes an AI prompt template at _prompts/add-theme.md that guides you through creating custom color themes with coordinated typography.

What it does:

Interviews you about color preferences, navbar style, and aesthetic goals
Generates complete OKLCH color palettes with accessible contrast ratios
Creates theme definitions for _sass/_color-tokens.scss
Adds theme documentation to _data/theme.yml
Optionally suggests Google Font pairings

How to use with an LLM:

With Claude Code (local):
- Open _prompts/add-theme.md in your project
- Ask Claude Code to read the file and follow its instructions
- Claude will ask for your theme details and make the necessary edits
With Claude.ai (online):
- Open _prompts/add-theme.md in your repository
- Copy the contents and paste into a new conversation at claude.ai
- Attach these files as context:
  - _sass/_color-tokens.scss
  - _data/theme.yml
  - _includes/head/theme-fonts.html (if adding font pairing)
- Answer the prompts about your desired theme
- Claude will provide the code changes to copy into your files
With other LLMs:
- The prompt is designed to work with any AI assistant
- Provide the prompt contents and the three files above
- Follow the generated instructions to add your theme

Example workflow:

You: "I want to create a theme called 'forest' with deep evergreen colors"

LLM: "What hue should the theme use? (0-360 degrees, or describe the color)"
You: "Deep forest green, around 150 degrees"

LLM: "Should the navbar be dark (white text) or light (dark text)?"
You: "Dark navbar with cream text"

[LLM generates complete theme code for _color-tokens.scss and theme.yml]

The prompt uses CB-Essay’s OKLCH color system to ensure your custom theme has proper contrast ratios and coordinates navbar, link, accent, and UI colors automatically.

For complete theme documentation, see Theme Options Guide.

Print & PDF Output

Generate publication-ready PDFs directly from your browser using Paged.js.

Print Hub

Visit /print/ to:

Print individual essays or build custom books
Choose Letter, A4, or 6×9″ page formats
Preview paginated layout before printing

Configuration

Configure print output in _data/theme.yml:

print:
  author: "Your Name"     # Author on cover and in PDF metadata
  institution: "Your Org" # Institution on cover
  aside-style: margin     # margin (floats into gutter) or inline (callout blocks)

What Works in Print

✅ Supported: Blockquotes, asides, images, section breaks, footnotes (as endnotes), running headers, page numbers, table of contents

❌ Web-only: Mini-maps, timelines, videos, iframes

Optimization

Use high-resolution images (1200px+ width)
Keep aside text concise
Test margin vs inline aside styles
Preview early and often

For complete details on page formats, accessibility features, and technical specifications, visit the Print Hub.

Gutenberg Extractor

CB-Essay includes a GitHub Action to import 60,000+ public domain books from Project Gutenberg directly into your _essay/ folder.

How to Use

Go to Actions tab in your GitHub repository
Click “Extract Gutenberg Book” workflow
Click “Run workflow”
Enter a book ID (e.g., 84 for Frankenstein, 1342 for Pride and Prejudice)
Click “Run workflow”

The book extracts as formatted Markdown files in _essay/ with proper front matter and chapter organization.

Finding Book IDs

Search Project Gutenberg
Find the book ID in the URL: https://www.gutenberg.org/ebooks/84 → ID is 84

What Gets Extracted

Chapter-by-chapter Markdown files
Metadata (title, author, publication info)
Cover image (when available)
Interior illustrations
Proper front matter with sequential ordering

After Extraction

Review the extracted files in _essay/
Adjust order values if needed
Add essay features (blockquotes, asides, etc.)
Customize theme in _data/theme.yml
Commit and push

For technical details, see Gutenberg Extraction Guide.

Publishing

GitHub Pages (Free)

Push changes to your main branch
GitHub Pages automatically rebuilds (2-3 minutes)
Site is live at https://username.github.io/repository-name

Custom domain:

Add CNAME file to repository root with your domain
Configure DNS with your domain provider
See GitHub Pages custom domain docs

Local Preview

bundle exec jekyll s

Visit http://localhost:4000 to preview changes before pushing.

Production Build

JEKYLL_ENV=production bundle exec jekyll build

Outputs to _site/ directory with full meta tags and analytics.

For complete deployment options, see CollectionBuilder Deploy Docs.

CollectionBuilder Features

When to use this section: Advanced features for working with your collection metadata - timelines, maps, data downloads, and metadata configuration.

CB-Essay includes all standard CollectionBuilder pages and features. This section is for advanced users who want to customize CollectionBuilder visualizations and pages.

Built-in Pages

Browse - Grid/list view of all items
Map - Geographic visualization (for items with coordinates)
Timeline - Chronological visualization (for items with dates)
Subjects - Word cloud of subject terms
Data - Downloadable metadata and visualizations

Feature Includes

Available for use in essays:

item-card.html - Display individual items
timeline.html - Embed timelines
cloud.html - Subject/location clouds
image.html - Single images
pdf.html - Embedded PDFs
video.html - Embedded videos

Metadata Configuration

Configure feature displays using CSV files in _data/:

config-browse.csv - Browse page fields
config-metadata.csv - Item page display
config-map.csv - Map configuration
config-search.csv - Search fields
config-table.csv - Data table columns

Complete Documentation

For full CollectionBuilder documentation:

Troubleshooting

Essay Issues

Essay doesn’t appear:

Check order field exists and is numeric in front matter
Verify file is in _essay/ directory
Confirm front matter is valid YAML (proper --- markers)
Check _site/essay/ directory after build

Prev/Next buttons missing:

Need at least 2 essays for navigation
Verify order values are set
Check layout is essay-content (should be automatic)

Include doesn’t work:

Check Liquid syntax: {% %} tags must be exact
Verify objectid exists in metadata CSV
Check browser console for errors
Ensure no extra spaces in tag syntax

Collection Item Issues

Item doesn’t display in aside:

Verify objectid exists in _data/[metadata].csv
Check objectid spelling matches exactly (case-sensitive)
Ensure item has fields: display_template, image_small, image_thumb
Test that item page loads: /items/objectid.html

Theme Issues

Table of contents not showing:

Verify show-homepage-toc: true in _data/theme.yml
Check essays have order field in front matter
Rebuild site (may need to clear cache)

Featured image not displaying:

Check image path (relative paths from site root)
Verify image file exists in repository
Check image-style is set in theme.yml
Look for 404 errors in browser console

Build Issues

Site not updating:

Wait 2-3 minutes for GitHub Pages rebuild
Check Actions tab for build errors

Local build fails:

Run bundle install to update dependencies
Check Ruby version (3.x recommended)
Review error messages for missing gems
See CollectionBuilder troubleshooting

Common Errors

Liquid syntax error:

Make sure includes use proper syntax:
{% include path.html param="value" %}
Not: { include path.html }

YAML parsing error:

Check front matter:
- Use --- markers top and bottom
- Proper indentation (spaces, not tabs)
- Quote values with special characters

Missing objectid:

Error: objectid "demo_001" not found
Solution: Check CSV file has matching objectid in metadata

External Resources

Documentation

Community & Support

Learning Resources

Ready to start? Check out the demo essays to see CB-Essay in action, then create your first essay in the _essay/ folder!

Overview

What Makes CB-Essay Different?

Perfect For

Quick Start

1. Get the Template

2. Enable GitHub Pages

3. Create Your First Essay

Essay Writing

File Structure

Required Front Matter

Optional Front Matter

Navigation

Workflow

Essay Features

Blockquotes

Asides (Margin Notes)

Image Galleries

Mini Maps

Section Breaks

Complete Feature Reference

Collection Integration

Using Collection Items

Metadata Requirements

CollectionBuilder Features in Essays

Theme Options

Homepage Image Options

Navigation and Homepage Layout Options

Color Themes

Typography & Fonts

Creating Your Own Theme

Print & PDF Output

Print Hub

Configuration

What Works in Print

Optimization

Gutenberg Extractor

How to Use

Finding Book IDs

What Gets Extracted

After Extraction

Publishing

GitHub Pages (Free)

Local Preview

Production Build

CollectionBuilder Features

Built-in Pages

Feature Includes

Metadata Configuration

Complete Documentation

Troubleshooting

Essay Issues

Collection Item Issues

Theme Issues

Build Issues

Common Errors

External Resources

Documentation

Community & Support

Learning Resources