Onboarding: sjmoran/sjmoran.github.io

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/sjmoran/sjmoran.github.io shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Solo project — review before adopting

• Last commit 1d ago
• CC0-1.0 licensed
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No CI workflows detected
• ⚠ No test directory detected
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live sjmoran/sjmoran.github.io repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sjmoran/sjmoran.github.io.

What it runs against: a local clone of sjmoran/sjmoran.github.io — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in sjmoran/sjmoran.github.io | Confirms the artifact applies here, not a fork | | 2 | License is still CC0-1.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>sjmoran/sjmoran.github.io</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sjmoran/sjmoran.github.io. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sjmoran/sjmoran.github.io.git
#   cd sjmoran.github.io
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of sjmoran/sjmoran.github.io and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sjmoran/sjmoran.github.io(\\.git)?\\b" \\
  && ok "origin remote is sjmoran/sjmoran.github.io" \\
  || miss "origin remote is not sjmoran/sjmoran.github.io (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(CC0-1\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"CC0-1\\.0\"" package.json 2>/dev/null) \\
  && ok "license is CC0-1.0" \\
  || miss "license drift — was CC0-1.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "_config.yml" \\
  && ok "_config.yml" \\
  || miss "missing critical file: _config.yml"
test -f "_layouts/default.html" \\
  && ok "_layouts/default.html" \\
  || miss "missing critical file: _layouts/default.html"
test -f "assets/css/style.scss" \\
  && ok "assets/css/style.scss" \\
  || miss "missing critical file: assets/css/style.scss"
test -f "_includes/hero.html" \\
  && ok "_includes/hero.html" \\
  || miss "missing critical file: _includes/hero.html"
test -f "assets/js/site.js" \\
  && ok "assets/js/site.js" \\
  || miss "missing critical file: assets/js/site.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/sjmoran/sjmoran.github.io"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

A Jekyll-based personal website and portfolio for Sean J Moran built with HTML, SCSS, and JavaScript. It serves as a professional homepage showcasing publications, patents, selected work, side-projects, and writing, compiled from template includes into static HTML pages via the Jekyll static site generator. Standard Jekyll site structure: _layouts/default.html wraps pages, _includes/ contains reusable components (hero.html, publications.html, patents.html, contact.html, writing.html, side-projects.html, now.html), _sass/ holds SCSS (fonts.scss, theme overrides, syntax highlighting via rouge-github.scss), and assets/ serves compiled CSS and custom fonts (Noto Sans family). The _config.yml drives Jekyll configuration.

Who it's for

Academic researchers and technical professionals who want to maintain a polished, customizable personal website without managing a database or server—specifically someone in computer science/research publishing papers and patents that need prominent display.

Maturity & risk

Stable and production-ready. This is a personal site currently deployed (live homepage for Sean J Moran), using the mature Jekyll framework with a minimal theme base, and no indication of recent active development beyond maintenance. The codebase is well-organized with clear separation of layouts and includes, suggesting it has been refined over time.

Very low risk. It is a static site with minimal dependencies (Jekyll, Ruby, SCSS compiler)—no external APIs, databases, or complex runtime behavior. Single-maintainer personal project means no breaking changes are expected, though updates to Jekyll or its theme dependencies could require minor template adjustments.

Active areas of work

No active development signals visible from file list alone (no recent commits, issue counts, or PR data provided). The site is static and stable; changes would be manual updates to publications, patents, or writing sections in the include files.

Get running

Clone the repo, install Ruby dependencies via Bundler, and serve locally:

git clone https://github.com/sjmoran/sjmoran.github.io.git
cd sjmoran.github.io
bundle install
bundle exec jekyll serve

The site will be available at http://localhost:4000.

Daily commands: Development server: bundle exec jekyll serve (watches for changes, rebuilds automatically). Production build: bundle exec jekyll build (outputs static files to _site/ for deployment to GitHub Pages or other static hosting).

Map of the codebase

• _config.yml — Jekyll configuration file that defines site metadata, theme settings, and build parameters—essential for understanding how the site is generated and deployed.
• _layouts/default.html — Master layout template that wraps all content; any changes to site structure, navigation, or global styling flow through this file.
• assets/css/style.scss — Primary stylesheet that imports theme and custom styles; controls the visual presentation of the entire site.
• _includes/hero.html — Landing page hero section; likely the first user-facing component and entry point for the homepage experience.
• assets/js/site.js — Main JavaScript file for client-side interactivity; handles dynamic behavior across the site.
• README.md — Project documentation that explains the site's purpose, setup, and deployment workflow.

Components & responsibilities

• Layout (_layouts/default.html) (Liquid templating, Jekyll variables) — Wraps all page content with header, footer, and global structure; includes navigation and site-wide assets.
  • Failure mode: Broken layout affects entire site; critical for structure integrity.
• Content Includes (_includes/) (Liquid, HTML, Markdown) — Modular sections for hero, publications, patents, projects, and contact; independently rendered and composable.
  • Failure mode: Missing or malformed include breaks that content section; isolated impact.
• Styling (SCSS + fonts) (SCSS, CSS, embedded fonts) — Defines visual presentation, typography, and responsive breakpoints; compiled to CSS at build time.
  • Failure mode: CSS compilation errors or missing fonts degrade visual presentation; does not prevent page load.
• Static assets (images, favicon) — undefined

How to make changes

Add a new portfolio project to featured work

1. Create a new include file for the project component in _includes/ (_includes/[project-name].html)
2. Add a project image to the img/ directory with descriptive naming (img/[project-name].png)
3. Reference the new include in the main layout or create a dedicated section include (_layouts/default.html)
4. Add a BibTeX entry if the project has an associated publication (bib/[project-name].bib)

Add a new publication or patent

1. Create a new BibTeX file in the bib/ directory with the citation details (bib/[publication-name].bib)
2. Add or update the corresponding include file (publications.html or patents.html) to reference the new entry (_includes/publications.html)
3. If needed, add a thumbnail image in the img/ directory (img/[publication-name].png)

Customize site styling

1. Edit the main stylesheet to add or modify CSS rules (assets/css/style.scss)
2. If adding custom fonts, add font-face definitions in the fonts SCSS file (_sass/fonts.scss)
3. Place font files in the assets/fonts/ directory with appropriate format variants (assets/fonts/[font-name]/)
4. Rebuild and test locally using Jekyll (_config.yml)

Update site metadata and configuration

1. Edit the Jekyll configuration file to update site title, description, author, and build settings (_config.yml)
2. Update the README with current project description and setup instructions (README.md)
3. Modify the main layout if global header/footer structure changes (_layouts/default.html)

Why these technologies

• Jekyll — Static site generator ideal for portfolios; enables version control, easy deployment to GitHub Pages, and minimal hosting overhead.
• SCSS/CSS — Stylesheet preprocessing allows organized, maintainable styling with variables and mixins; compiled to plain CSS for browser delivery.
• Noto Sans fonts (custom embedded) — Self-hosted typography provides consistent branding, faster performance than external CDNs, and guaranteed availability.
• GitHub Pages — Native Jekyll integration, free hosting, automatic deployment from git pushes, and built-in HTTPS for professional presence.
• BibTeX — Academic standard for publication metadata; enables easy citation generation and management of research bibliography.

Trade-offs already made

• Static site generation vs. dynamic backend

  • Why: Portfolio content is relatively stable and does not require real-time updates or user interactivity.
  • Consequence: Faster load times, lower infrastructure costs, and easier deployment; but limits real-time content updates and personalization.

• Self-hosted fonts vs. CDN fonts

  • Why: Ensures consistent typography rendering and avoids external CDN latency and privacy concerns.
  • Consequence: Slightly larger initial page weight from font files (~50-100KB) but guaranteed availability and better performance for repeat visitors.

• Minimal JavaScript (site.js)

  • Why: Portfolio is primarily informational with limited interactivity needs.
  • Consequence: Lightweight client-side footprint improves performance; complex interactive features would require architectural changes.

• Modular include architecture

  • Why: Enables reusable, maintainable content sections that can be individually updated without touching the main layout.
  • Consequence: Adds organizational overhead for very simple sites; benefits scale with content growth.

Non-goals (don't propose these)

• Real-time content updates or server-side rendering
• User authentication or personalization
• Database-backed content management
• SEO optimization beyond static metadata
• Mobile app or native client

Traps & gotchas

Ruby version pinning: Gemfile.lock may enforce specific Ruby/Bundler versions; if you encounter build failures, check Gemfile for version constraints and run bundle update with caution. Font loading: Multiple font formats (eot, svg, ttf, woff, woff2) in assets/fonts/Noto-Sans-* are pre-declared in _sass/fonts.scss—if you swap fonts, ensure all weight/style variants are present or CSS @font-face rules will break. Jekyll version: jekyll-theme-minimal may have compatibility requirements; changes to Jekyll core between major versions could break Liquid template syntax. Static deployment assumption: This site is built to be served from sjmoran.github.io (GitHub Pages); custom domain or subdirectory hosting may require changes to _config.yml baseurl setting. Bibliography source of truth: The .bib files in bib/ directory are tracked but it's unclear if they feed publications.html automatically or are manually maintained in parallel—check how publications.html consumes this data.

Architecture

Concepts to learn

• Jekyll static site generation — This repo depends entirely on Jekyll's Liquid template engine, build pipeline, and plugin architecture to transform source files into deployable HTML; understanding how Jekyll processes _layouts/, _includes/, and front-matter is prerequisite knowledge
• SCSS/SASS preprocessing — The codebase uses nested SCSS in _sass/ to manage fonts, theme overrides, and syntax highlighting; learning SCSS variables, mixins, and nesting will help you modify and extend styles efficiently
• Web font subsetting and multi-format fallbacks — The assets/fonts/Noto-Sans-* directories contain fonts in 5 different formats (eot, svg, ttf, woff, woff2) and multiple weights/styles (regular, italic, 700, 700italic); understanding why each format exists (browser compatibility, file size, performance) is important for maintaining or replacing fonts
• BibTeX bibliography format — The bib/ directory contains .bib files which are standard academic bibliography sources; if you need to update publications or understand how citations are structured, you should be familiar with BibTeX syntax and fields (author, title, journal, year, etc.)
• GitHub Pages deployment model — This is a GitHub Pages site (repo name ends in .github.io); understanding how GitHub Pages builds Jekyll sites on push and serves static content from branches (main/master) is essential for deployment workflows
• Liquid template language — Jekyll uses Liquid for dynamic templating (variable interpolation, includes, loops, conditionals); you'll see Liquid syntax in _layouts/default.html and all _includes/*.html files
• Responsive design and CSS media queries — While not explicitly visible in the file list, a modern personal portfolio should handle mobile and desktop viewports; understanding how SCSS media queries work (as likely used in the minimal theme) is important for maintaining responsive layout

Related repos

• jekyll/jekyll — The static site generator that powers this entire project; understanding Jekyll's Liquid templating and plugin system is essential to extending this site
• pages-themes/minimal — The official GitHub Pages minimal theme that this repo inherits from (imported in _config.yml); source of the base styling and layout structure
• jpsim/SourceKitten — Example of how a personal GitHub Pages site can showcase a technical project with bibliographic data and patent info (similar portfolio use case)
• github/gitignore — Reference for understanding the .gitignore rules in this repo and best practices for Ruby/Jekyll projects
• rouge-ruby/rouge — The syntax highlighter that powers rouge-github.scss for code block styling on the site

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Jekyll build validation and link checking GitHub Action

This personal website uses Jekyll but has no CI pipeline to validate builds or check for broken links. The repo contains 20+ .bib files and multiple include files that could have broken references. A GitHub Action would catch build failures and broken links before deployment.

• [ ] Create .github/workflows/jekyll-build.yml with jekyll build step
• [ ] Add html-proofer step to validate all links in _includes/*.html and generated _site/
• [ ] Configure to run on push to main and pull requests
• [ ] Test against the 20+ .bib files in /bib directory to ensure publication references resolve

Create data-driven publication/patent management system

Currently _includes/publications.html and _includes/patents.html are separate HTML files. The repo has 20+ individual .bib files but no structured data layer. Creating a _data/publications.yml or similar would eliminate duplication, make maintenance easier, and allow the includes to iterate programmatically rather than hardcode content.

• [ ] Extract publication entries from _includes/publications.html into _data/publications.yml with fields: title, authors, venue, year, bib_file
• [ ] Extract patent entries from _includes/patents.html into _data/patents.yml with similar structure
• [ ] Refactor _includes/publications.html to loop through site.data.publications instead of hardcoded HTML
• [ ] Refactor _includes/patents.html to loop through site.data.patents instead of hardcoded HTML
• [ ] Verify all 20+ .bib files are properly referenced in the new data files

Consolidate font asset delivery and add font loading performance optimization

The repo has 12 custom font files (Noto-Sans variants) spread across assets/fonts/ with multiple formats (.eot, .svg, .ttf, .woff, .woff2). The current _sass/fonts.scss likely uses @font-face declarations without optimization. Adding font-display: swap and preload hints would improve Core Web Vitals and reduce Cumulative Layout Shift.

• [ ] Review current @font-face declarations in _sass/fonts.scss
• [ ] Add font-display: swap to all @font-face rules to prevent invisible text during load
• [ ] Add <link rel="preload"> tags in _layouts/default.html for critical fonts (Noto-Sans-regular minimum)
• [ ] Add <link rel="dns-prefetch"> if any fonts are served from CDN
• [ ] Test font loading performance with Lighthouse and document results in updated README

Good first issues

• Add responsive testing or missing mobile styles: The file list shows SCSS exists but no indication of media queries or responsive breakpoint testing; add or verify mobile-first breakpoints (max-width: 768px, 480px) in _sass/jekyll-theme-minimal.scss and test on actual devices or browser DevTools.
• Document or fix bibliography import: The bib/ folder contains .bib files (acl14.bib, carpentry.bib, curl.bib, deeplpf.bib) but it's unclear if _includes/publications.html auto-parses them or if they're manually synced; audit the publications include and either document the sync process or automate it via a Jekyll plugin.
• Add accessibility audit: Review _layouts/default.html and includes for missing ARIA labels, alt text on images, semantic HTML5 elements (nav, article, section, main), and heading hierarchy (h1 before h2/h3); this is especially important for a professional portfolio site.

Top contributors

• @sjmoran — 1 commits

Recent commits

• 72f5343 — Personal site (sjmoran)

Security observations

This is a static Jekyll-based personal website with a relatively good security posture. No critical vulnerabilities were identified. The main concerns are: (1) missing explicit security headers configuration, (2) potential XSS risks in HTML includes if unvalidated data is rendered, (3) large binary files in git history, and (4) need for regular dependency auditing. The static nature of the site significantly reduces attack surface compared to dynamic applications. Recommendations include implementing security headers at the web server/hosting level, validating all dynamic content in includes, using Git LFS for assets, and establishing a dependency scanning routine.

• Low · Missing Security Headers Configuration — _config.yml. The Jekyll site configuration does not explicitly define security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.). While Jekyll sites are static, the deployment environment may not enforce these headers by default. Fix: Configure security headers in the web server (nginx/Apache) or deployment platform (GitHub Pages). Add CSP headers to restrict inline scripts and external resource loading.
• Low · Potential XSS via Unvalidated Includes — _includes/contact.html, _includes/email.html. Multiple HTML include files (_includes/*.html) may render user-provided content or dynamic data. If any of these includes process unsanitized input from Jekyll data files or front matter, XSS vulnerabilities could occur. Fix: Review all include files to ensure proper HTML escaping. Use Jekyll's liquid filters like 'escape' or 'xml_escape' for any dynamic content rendering.
• Low · Large Binary Files in Version Control — bib.zip, img/1809-1min.wmv, assets/fonts/. The repository contains binary media files (bib.zip, .wmv video, multiple image formats) and font files checked into Git. This increases repository size and may pose supply chain risks if files are modified. Fix: Use Git LFS (Large File Storage) for binary assets. Store large media files on a CDN. Remove bib.zip from version control and generate dynamically if needed.
• Low · Missing CORS/CSRF Protection Configuration — _includes/contact.html. The contact.html include suggests a contact form, but there's no visible CSRF token implementation or CORS policy configuration. Fix: Implement CSRF protection tokens in forms. Configure appropriate CORS headers if the site makes cross-origin requests. Use honeypot fields for bot detection.
• Low · No Explicit Dependency Lock Version — Gemfile, Gemfile.lock. While Gemfile.lock exists, Ruby gem versions may have known vulnerabilities. The Gemfile and dependencies were not provided for detailed analysis. Fix: Regularly run 'bundle audit' to check for vulnerable gems. Keep Jekyll and all dependencies updated. Consider using Dependabot for automated vulnerability scanning.
• Low · Potential Information Disclosure via Metadata — .DS_Store. The .DS_Store file indicates Mac development environment. System files and editor configs should not be in version control as they may expose development patterns or tools. Fix: Remove .DS_Store, ensure .gitignore properly excludes OS-specific files (.DS_Store, Thumbs.db, .vscode/, .idea/), and ensure no sensitive IDE configurations are committed.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.