Setup Guide

Quick Start (GitHub Pages - Recommended)

The easiest way to deploy this site is via GitHub Pages, which handles all the building automatically:

Create a new GitHub repository
- Go to https://github.com/new
- Name it whatever you like (e.g., my-research-site)
- Public or private (both work with GitHub Pages)

Initialize Git and push

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPO.git
git branch -M main
git push -u origin main

Enable GitHub Pages
- Go to your repository Settings → Pages
- Source: “Deploy from a branch”
- Branch: main, folder: / (root)
- Click Save
Wait 2-3 minutes
- GitHub will build your site automatically
- Visit https://YOUR-USERNAME.github.io/YOUR-REPO/

That’s it! GitHub handles all the Jekyll building, Ruby dependencies, etc.

Local Development (Optional)

If you want to preview changes locally before pushing:

Requirements

Ruby 3.0+ (check with ruby -v)
Bundler (gem install bundler)

Install Ruby 3.0+ (if needed)

macOS (using Homebrew):

# Install rbenv
brew install rbenv ruby-build

# Install Ruby 3.3
rbenv install 3.3.0
rbenv global 3.3.0

# Add to shell (add to ~/.zshrc or ~/.bash_profile)
eval "$(rbenv init -)"

# Restart terminal, verify
ruby -v  # Should show 3.3.0

Or use system Ruby if 3.0+:

ruby -v
# If 3.0 or higher, you're good

Build Site Locally

# Install dependencies
bundle install

# Serve locally (with live reload)
bundle exec jekyll serve --livereload

# Open http://localhost:4000

Common Issues

“Ruby version not compatible”

Upgrade Ruby to 3.0+ (see above)
Or just use GitHub Pages and skip local development

“Bundle not found”

gem install bundler

Port 4000 already in use

bundle exec jekyll serve --port 4001

Updating Content

Add a New Post

Create markdown file in _posts/:
- Filename format: YYYY-MM-DD-title.md
- Example: 2026-03-15-new-results.md

Add front matter:

---
layout: post
title: "My New Results"
date: 2026-03-15
author: Anthony Grigsby
use_plot: true
plot_script: /assets/js/2026-03-15-plots.js
---

Add data files to assets/data/:
```
cp data/2026-03-15/*.csv assets/data/
```
Create visualizations in assets/js/2026-03-15-plots.js
- Use 2026-02-23-plots.js as a template
- Adjust data filenames and plot IDs

Commit and push:

git add .
git commit -m "Add new post"
git push

GitHub Pages will rebuild automatically (2-3 minutes).

Customization

Site Info

Edit _config.yml:

title: Your Name
email: your.email@example.com
description: Your research focus
github_username: your-github

Styling

Edit assets/css/main.css for colors, fonts, layout.

Homepage

Edit index.md to change homepage content.

File Structure

.
├── _config.yml              # Site configuration
├── _posts/                  # Blog posts (markdown)
│   └── YYYY-MM-DD-title.md
├── _layouts/                # Page templates
│   ├── default.html         # Base template
│   ├── post.html           # Blog post template
│   └── ...
├── assets/
│   ├── css/main.css        # Styling
│   ├── data/               # CSV data files
│   └── js/                 # Observable Plot scripts
├── index.md                # Homepage
├── blog.md                 # Blog index
└── README.md               # Documentation

Observable Plot Examples

Load CSV data:

const data = await d3.csv('/assets/data/myfile.csv', d3.autoType);

Create a box plot:

const plot = Plot.plot({
  marks: [
    Plot.boxX(data, {x: "value", y: "group"})
  ]
});
document.getElementById('my-plot').appendChild(plot);

Scatter with facets:

Plot.plot({
  facet: {data: data, y: "species"},
  marks: [
    Plot.dot(data, {x: "PC1", y: "PC2", fill: "species"})
  ]
})

See Observable Plot docs for more.

Troubleshooting

Site not updating after push

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

Plots not showing

Check browser console (F12) for errors
Verify CSV files are in assets/data/
Verify use_plot: true in post front matter

404 on GitHub Pages

Make sure Pages is enabled in Settings
Check that baseurl in _config.yml matches your repo name
May need: baseurl: "/your-repo-name"