McGarrah Technical Blog

Jekyll Run Plugin: Fixing the Multi-Root Workspace Crash

2026-07-14T00:00:00+00:00

In my previous post on the Jekyll Run plugin, I covered how to configure the extension for local development — the flags that matter, settings precedence, and the _config.yml trap. That post assumed the plugin actually starts. This one covers what happens when it doesn’t.

If you use a multi-root workspace in VS Code on macOS, the Jekyll Run extension crashes before it even tries to run Jekyll. The error is unhelpful:

TypeError: Cannot read properties of null (reading 'toString')

No stack trace in the UI. No hint about what’s null. Just a dead button. I spent hours chasing this through VS Code settings, plugin source code, and compiled JavaScript patches before finding the real cause — and it had nothing to do with any of that. Misleading error messages that point to the wrong layer are the most expensive bugs to diagnose — true in VS Code extensions and equally true in distributed systems.

The Symptom

You open a multi-root workspace with your Jekyll blog and other projects. You click the Jekyll Run button in the status bar. Instead of building your site, you get the TypeError. The extension does nothing.

The same workspace, same plugin version, same settings — works fine on WSL2. Only macOS is broken.

My first theory was settings precedence. The plugin reads its configuration via getConfiguration().get('jekyll-run'), and I knew VS Code settings come from multiple sources with complex override rules. In a multi-root workspace, an empty "settings": {} in the .code-workspace file could shadow per-folder settings.

I added jekyll-run settings to every possible location:

Location	Result
`.vscode/settings.json` (workspace folder)	Crash
`.code-workspace` settings block	Crash
VS Code User settings	Crash
All three simultaneously	Crash

None of them fixed it. The settings were correct everywhere, but the plugin still crashed.

I dug into the plugin’s compiled JavaScript. The Config.get() method uses an unscoped API call:

// out/config/config.js
return vscode.workspace.getConfiguration().get(extension);

The VS Code API documentation recommends getConfiguration('jekyll-run') (passing the section name directly) instead of getConfiguration().get('jekyll-run') (fetching the root and extracting a key). The unscoped form can return null in multi-root workspaces.

I patched config.js to use the scoped form. The TypeError persisted. The settings were resolving correctly — the crash was happening somewhere else entirely.

Blind Alley #3: `.zshenv`

I noticed the plugin spawns bundle exec jekyll serve with { shell: true }. On macOS, VS Code launched from the Dock doesn’t source ~/.zshrc. I created ~/.zshenv (which is supposed to be sourced by all zsh instances, including non-interactive ones) with the Homebrew Ruby PATH.

Fully quit VS Code, reopened — still system Ruby 2.6. VS Code’s extension host process isn’t a zsh instance, so .zshenv is never sourced.

The Breakthrough: Developer Tools

The actual error was hiding in plain sight. Opening VS Code’s Developer Tools (Cmd+Shift+P → “Toggle Developer Tools” → Console tab) revealed the real error above the TypeError:

stderr: /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/rubygems.rb:283:
in `find_spec_for_exe': Could not find 'bundler' (4.0.8) required by your Gemfile.lock.
(Gem::GemNotFoundException)

The plugin was running macOS system Ruby 2.6 — not my Homebrew Ruby. System Ruby doesn’t have the correct bundler version, so bundle exec jekyll serve fails immediately.

The TypeError was a secondary crash in the plugin’s error handler. When stderr contains “ruby”, the plugin tries to extract an Errno message:

reject(error.match(/\B(.+)Errno(.+)/m));

The bundler error doesn’t contain “Errno”, so match() returns null. The plugin calls reject(null), and the caller does null.toString() — crash. The real error (wrong Ruby) is swallowed. The user sees only the misleading TypeError.

The Root Cause: macOS GUI PATH Inheritance

On macOS, applications launched from the Dock, Spotlight, or Finder inherit their environment from launchd, not from your shell. Your ~/.zshrc PATH modifications — including Homebrew Ruby — are invisible to VS Code when launched this way.

# Your terminal sees:
which ruby    → /opt/homebrew/opt/ruby/bin/ruby  (Homebrew Ruby 4.0)

# VS Code's spawned processes see:
which ruby    → /usr/bin/ruby                     (macOS system Ruby 2.6)

WSL2 works because VS Code Remote Server runs inside a login shell that sources ~/.zshrc. Same plugin, same workspace, same settings — but different environment inheritance model.

The Solution: rbenv + Launch from Terminal

The fix has three parts:

1. Use rbenv for Ruby Version Management

Homebrew Ruby 4.0 has its own problem — --livereload causes a thread exception popup with Jekyll 4.4.1. Rather than fight bleeding-edge compatibility issues, use rbenv to pin the project to Ruby 3.3, which works perfectly with all Jekyll features:

# Install rbenv
brew install rbenv ruby-build

# Install Ruby 3.3
rbenv install 3.3.11

# Set project-local Ruby version
cd mcgarrah.github.io
rbenv local 3.3.11    # creates .ruby-version

# Install gems under Ruby 3.3
gem install bundler
bundle install

2. Initialize rbenv in Your Shell

Add to ~/.zshrc (before source $ZSH/oh-my-zsh.sh):

# rbenv Ruby version manager (macOS only)
# Uses .ruby-version in project directories to select the correct Ruby
if [[ "$(uname -s)" == "Darwin" ]]; then
  eval "$(rbenv init - zsh)"
fi

And create ~/.zshenv so non-interactive shells (like those VS Code spawns) can find rbenv’s shims:

# rbenv shims for non-interactive shells (VS Code extensions)
if [[ "$(uname -s)" == "Darwin" && -d "$HOME/.rbenv" ]]; then
  export PATH="$HOME/.rbenv/shims:$HOME/.rbenv/bin:$PATH"
fi

3. Launch VS Code from a Terminal

macOS GUI apps don’t source any shell configuration files. The ~/.zshenv file helps with some non-interactive shells, but VS Code’s extension host may still not pick it up reliably. The bulletproof fix is to launch VS Code from a terminal where your PATH is correct:

code ~/Personal/Github-mcgarrah/articles-workspace.code-workspace

When VS Code is launched this way, it inherits the terminal’s environment, including rbenv’s shims. The plugin finds the correct bundle and ruby executables, and Jekyll starts with all features working — including --livereload.

Why Ruby 3.3 Instead of 4.0

Homebrew Ruby 4.0.2 works for Jekyll builds, but --livereload triggers a thread exception:

# terminated with exception

The site still serves, but the popup is disruptive. Ruby 3.3.11 has no such issue — all Jekyll 4.4.1 features work correctly, including livereload.

Using rbenv with a .ruby-version file means:

The Jekyll project uses Ruby 3.3 (stable, fully compatible)
Other projects can use whatever Ruby they need
The version is committed to the repository so collaborators get the same Ruby
GitHub Actions can read .ruby-version to match the local development environment

The Plugin Bug (Still Real)

The misleading TypeError is a genuine bug in the plugin’s error handling, separate from the PATH issue. The plugin hasn’t been updated since 2020 (GitHub: Kanna727/jekyll-run).

Two issues worth a PR:

1. Null rejection on non-Errno errors in src/cmds/run.ts:

-            reject(error.match(/\B(.+)Errno(.+)/m));
+            reject(error.match(/\B(.+)Errno(.+)/m) || error);

2. Unscoped getConfiguration call in src/config/config.ts:

-        return vscode.workspace.getConfiguration().get(extension) as any;
+        return vscode.workspace.getConfiguration(extension);

The first fix ensures users see the actual Ruby error instead of a cryptic TypeError. The second fix properly resolves settings in multi-root workspaces. Neither is required if you follow the rbenv + terminal launch approach above, but both would make the plugin more robust.

Complete Setup Reference

Shell Configuration (`~/.zshrc`)

# rbenv Ruby version manager (macOS only)
if [[ "$(uname -s)" == "Darwin" ]]; then
  eval "$(rbenv init - zsh)"
fi

Shell Environment (`~/.zshenv`)

# rbenv shims for non-interactive shells (VS Code extensions)
if [[ "$(uname -s)" == "Darwin" && -d "$HOME/.rbenv" ]]; then
  export PATH="$HOME/.rbenv/shims:$HOME/.rbenv/bin:$PATH"
fi

Project Ruby Version (`.ruby-version`)

3.3.11

VS Code Settings (`.vscode/settings.json`)

{
    "jekyll-run.commandLineArguments": "--trace --drafts --future --unpublished --livereload --incremental",
    "jekyll-run.stopServerOnExit": true
}

Multi-Root Workspace (`.code-workspace`)

{
    "settings": {
        "jekyll-run.commandLineArguments": "--trace --drafts --future --unpublished --livereload --incremental",
        "jekyll-run.stopServerOnExit": true
    }
}

Fallback Script (`start-jekyll.sh`)

#!/bin/bash
bundle exec jekyll serve --trace --drafts --future --unpublished --livereload --incremental

Known Issue: Port Conflict Shows Thread Exception

If a Jekyll server is already running on port 4000 (from a terminal ./start-jekyll.sh session, for example), clicking the Jekyll Run button won’t show a clean “port in use” error. Instead, you’ll see a thread exception popup:

# terminated with exception

This happens because the plugin’s port-detection code parses lsof output by splitting on single spaces, but macOS lsof uses variable-width columns with multiple spaces between fields. The PID is never extracted, so the plugin thinks port 4000 is free, launches Jekyll, and the livereload thread crashes on the port conflict before the main server reports EADDRINUSE.

The workaround is to not run both simultaneously — use either ./start-jekyll.sh or the Jekyll Run button, not both. Kill the terminal server first (Ctrl+C) before using the plugin.

This is a separate plugin bug that will be covered in a future article on patching the source and submitting a PR.

Summary

Three problems, layered on top of each other, each masking the next:

Problem	Symptom	Fix
macOS GUI apps don’t inherit shell PATH	System Ruby 2.6 runs instead of project Ruby	Launch VS Code from terminal
Plugin rejects `null` on non-Errno Ruby errors	TypeError instead of useful error message	Plugin bug (PR needed)
Ruby 4.0 livereload incompatibility	Thread exception popup	Use Ruby 3.3 via rbenv
Plugin `lsof` parsing broken on macOS	Port conflict shows thread exception instead of clean error	Don’t run terminal server and plugin simultaneously; plugin bug (PR needed)

The first one is the blocker. The second makes debugging harder. The third drove the choice of Ruby 3.3 over 4.0. The fourth is a nuisance if you forget to stop a terminal server before using the plugin.

Jekyll Run Plugin: Local Development Settings That Actually Work — Complete configuration guide for the extension
Running GitHub Pages Jekyll Locally — Initial local development setup

References

Jekyll Run Extension — VS Code Marketplace
Jekyll Run Source Code — GitHub repository (last updated 2020)
rbenv — Ruby version manager
VS Code getConfiguration API — Official API documentation

The Google Services Tax on a Simple Blog

2026-07-07T00:00:00+00:00

Vendor service sprawl is a real operational cost, and Google is a case study in how “free” services accumulate complexity. Running a technical blog now requires integrating Analytics, Search Console, Custom Search, and AdSense — each with its own dashboard, approval process, privacy implications, and integration quirks. What should be a solved problem for a static site has become a multi-month project with opaque feedback loops and interconnected dependencies that don’t always play nicely together.

Lions and Tigers and AdSense, oh my.

I’ve been trying to get Google AdSense back online with my website for over a year with no success. I had it working on WordPress prior to 2016, but after migrating to Jekyll and consolidating decades of content, Google flagged my site for “duplicate content that appeared to be plagiarized.”

The irony? It was my own content from my previous blogs and websites, consolidated into one place. Fast forward to 2025, and I have over half my content generated in the last two years, yet AdSense still rejects my applications with vague, unhelpful feedback.

The Service Integration Treadmill

Each Google service requires its own setup dance, and they’re all interconnected in ways that aren’t immediately obvious:

Google Analytics: Set up in August 2024 during a website modernization push. Relatively straightforward, but required privacy policy updates and cookie consent considerations.

Google Search Console: This one bit me hard. Spent months with a broken sitemap because I had localhost:4000 URLs instead of my actual domain. The error messages were cryptic, and it took forever to realize the URL configuration issue.

Google Custom Search: A weird beast that sort of works but feels like a compromise. Better than no search, but the styling integration is a nightmare and it doesn’t always index new content promptly.

Google AdSense: The white whale. Still rejected after multiple attempts, vague feedback, and jumping through hoops like adding privacy policies, fixing “content quality” issues, and ensuring GDPR compliance.

The Google Service Complexity Matrix

Services I’m Actually Using:

Google Analytics: Works well once configured, but requires privacy policy updates and cookie consent banners for GDPR compliance
Google Search Console: Useful when it works, but error messages are cryptic and debugging sitemap issues is painful
Google Custom Search: Functional but feels like a hack - styling integration is terrible and indexing is inconsistent
Google AdSense: The promised land I can’t reach - endless rejections with vague feedback

Services I Think I Should Be Using:

Google Tag Manager: Supposedly simplifies tag management, but adds another layer of complexity
Google PageSpeed Insights: Helpful for performance, but recommendations often conflict with other Google service requirements
Google Optimize: A/B testing sounds great, but requires Tag Manager integration (more complexity)
Google Trends: Useful for content planning, but another dashboard to monitor

The Real Problem

Each service exists in its own silo with its own:

Dashboard and interface
Approval process and requirements
Integration complexity
Privacy and compliance implications
Performance impact on the website

What should be a simple “add analytics and search” becomes a multi-month project involving privacy policies, cookie banners, multiple dashboards, and endless troubleshooting of interconnected systems that don’t always play nicely together.

The Frustration Factor

The most maddening part? Google’s own services don’t integrate seamlessly with each other. You’d think Google Analytics and Google Search Console would share data more effectively, or that Google Custom Search would automatically index content that Google Search Console knows about.

Instead, each service feels like it was built by a different team with different assumptions about how websites work. The result is a fragmented experience that requires significant time investment to get working properly.

Maybe I’m overthinking this, but for a simple technical blog, the overhead of managing all these Google services sometimes feels like it outweighs the benefits. I just want a blog site to publish fun stuff I’m doing outside of work. On the upside, I’m keeping current on the same integration challenges that small and medium businesses face every day — vendor service sprawl, opaque approval processes, and the hidden cost of “free” platforms. Having managed similar vendor integration complexity in enterprise environments, I can say the pattern is identical at any scale — it just costs more when the stakes are higher.

What I’ve Actually Done About It

I’m not just complaining — I’ve been systematically attacking each of these problems. The results are mixed:

GDPR compliance — Built a full cookie consent implementation with region detection, consent management, and conditional script loading. This was a prerequisite for everything else.
AdSense approval — Documented the debugging process after repeated “site isn’t ready” rejections. Fixed the GDPR script loading interaction that was blocking the verification crawler. Improved E-E-A-T signals across the site. Still not approved. The rejections continue with the same vague feedback.
Sitemap issues — Fixed sitemap bloat from tags, categories, and pagination pages that were diluting the signal for actual content.
SEO infrastructure — Built an automated SEO health check into the CI/CD pipeline that validates canonical URLs, meta tags, structured data, and broken links on every push.
Search Console crawling — Still fighting crawler access issues. The Google bot reports pages it can’t reach, but the same pages load fine in a browser. The debugging cycle is: wait for crawl → read vague error → change something → wait weeks for re-crawl → repeat.

Months of work. Dozens of commits. Multiple published articles documenting the journey. And AdSense still says “no” without telling me why.

The Ongoing Battle

The frustrating truth is that there’s no finish line. Google’s approval processes are opaque, their feedback is generic, and their timelines are measured in weeks. You can do everything right — proper structured data, clean sitemaps, GDPR compliance, quality content, good E-E-A-T signals — and still get rejected with “Your site isn’t ready.”

I’ll keep documenting the fight. At minimum, the infrastructure improvements make the site better regardless of whether Google ever approves the ads. And the knowledge transfers directly to professional work — every small business website faces these same integration challenges.

Cheers from the Homelab.

Building a Draft Preview Site for Jekyll — Part 3: The Implementation

2026-06-30T00:00:00+00:00

In Part 1, I explored the options. In Part 2, I refined the design. Now it’s time to build it.

This is Part 3 of a three-part series:

Part 1: Exploring every option I considered
Part 2: Refining the design — config, workflow, feedback, and gaps
Part 3 (this post): The complete implementation

Status: The system is live at drafts.mcgarrah.org and deploying reliably on every push to main. What follows captures the real issues and fixes from first-run deployments — not just the design intent, but what actually happened.

Creating the Drafts Repo

The deployment target is mcgarrah/drafts.mcgarrah.org — a public repo that contains only built HTML output. I chose public because:

GitHub Pages on free accounts requires public repos
The source markdown is already public in mcgarrah.github.io
The HTML is Staticrypt-encrypted, so the rendered content isn’t casually browsable
The repo has no source code of value — it’s a deployment target, not a project

Setup steps:

Created the repo initialized with a README.md (critical — see below)
Enabled GitHub Pages: Settings → Pages → Deploy from branch → main → / (root)
Enabled GitHub Discussions with a dedicated “Draft Reviews” category for Giscus feedback
Generated a fine-grained GitHub PAT scoped to only the drafts.mcgarrah.org repo with repo permissions
Added DRAFTS_DEPLOY_TOKEN and DRAFTS_PASSWORD as secrets on the mcgarrah.github.io repo

The empty-repo trap: GitHub Pages cannot be configured on a truly empty repo because there’s no main branch to select. The Pages settings page just shows an error. The repo needs at least one commit before main exists and Pages can be enabled. Initializing with a README.md avoids this entirely.

DNS Configuration

One-time setup in Porkbun:

drafts.mcgarrah.org  CNAME  mcgarrah.github.io.

Propagation took under five minutes. After the first successful deployment, I enabled “Enforce HTTPS” in the drafts repo’s Pages settings — GitHub provisions a Let’s Encrypt certificate automatically.

The Config Overlay

The real _config_drafts.yml that’s deployed:

url: "https://drafts.mcgarrah.org"
canonical_url: "https://drafts.mcgarrah.org"
baseurl: ""
draft_preview_site: true
main_site_url: "https://mcgarrah.org"

# Disable production tracking and ads on the drafts preview site.
google_analytics: ""
google_adsense: ""
google_cse_id: ""

# Enable Giscus comments for the drafts preview site.
giscus:
  repo: mcgarrah/drafts.mcgarrah.org
  repo_id: R_kgDOSG6Quw
  category: Draft Reviews
  category_id: DIC_kwDOSG6Qu84C7PMZ
  mapping: pathname
  strict: 0
  reactions_enabled: 1
  emit_metadata: 0
  input_position: top
  theme: preferred_color_scheme
  lang: en
  loading: lazy

# Mark every rendered page as noindex on the drafts site.
defaults:
  - scope:
      path: ""
    values:
      noindex: true

Key decisions baked into this config:

draft_preview_site: true and main_site_url power the orange preview banner in the layout
The defaults: block sets noindex: true on every page site-wide. The layout picks this up as — the primary defense against search engine indexing
Giscus points to the drafts repo’s Discussions, keeping preview feedback completely separate from production comments
Analytics, AdSense, and custom search are all blanked — no tracking on the preview site

The Final Workflow

The workflow evolved significantly from the sketch in Part 2. The biggest change: selective encryption. Instead of encrypting every HTML file on the site, the workflow identifies only draft and future-dated post pages and encrypts those. Already-published content stays unencrypted — it’s public anyway, and encrypting it just adds build time and makes navigation annoying.

Here’s the structure of .github/workflows/deploy-drafts.yml:

name: Deploy Draft Preview Site

on:
  push:
    branches: ["main"]
  workflow_dispatch:

concurrency:
  group: drafts-pages
  cancel-in-progress: true

The concurrency group ensures only one drafts deployment runs at a time — if I push twice in quick succession, the second run cancels the first rather than racing.

Build Step

Standard Jekyll build with the config overlay:

- name: Build with Jekyll (drafts + future)
  run: bundle exec jekyll build --drafts --future --config _config.yml,_config_drafts.yml
  env:
    JEKYLL_ENV: production

Selective Encryption

This is the most complex step. The workflow:

Scans _drafts/ for files matching the YYYY-MM-DD-*.md pattern (skipping convenience files like DRAFTS.md)
Scans _posts/ for future-dated files (post date > today)
Maps each source file to its rendered HTML in _site/ using Jekyll’s permalink slug
Encrypts each file individually in an isolated temp directory to avoid Staticrypt’s basename collision problem

# Only encrypt if it starts with YYYY-MM-DD pattern (actual post format).
if [[ "$base" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2} ]]; then
  add_target_for_slug "$(slug_from_source_file "$source_file")"
fi

Each file is encrypted one at a time with hash-based verification:

before_hash="$(sha256sum "$file" | awk '{print $1}')"
cp "$encrypted_src" "$file"
after_hash="$(sha256sum "$file" | awk '{print $1}')"

if [[ "$before_hash" == "$after_hash" ]]; then
  echo "::error::Encryption did not modify $file (hashes match)"
  exit 1
fi

Staticrypt flags used:

--short — compact password prompt page
--remember 30 — stores the decryption key in localStorage for 30 days so reviewers don’t re-enter the password on every page click
--template-title "Draft Preview - mcgarrah.org" — custom title on the password prompt
-c false — disables Staticrypt’s config file creation (not needed in CI)
-d — output to a temp directory, then copy back to preserve the original path structure

Crawler Protections

- name: Apply crawler protections
  run: |
    printf "User-agent: *\nDisallow: /\n" > _site/robots.txt
    rm -f _site/feed.xml _site/sitemap.xml _site/sitemapindex.xml

    # Remove feed discovery hints from generated pages
    find _site -type f -name '*.html' \
      -exec sed -i.bak '/type="application\/atom+xml"/d' {} +
    find _site -type f -name '*.bak' -delete

Three layers of protection:

robots.txt with Disallow: / — tells well-behaved crawlers to stay away
noindex meta tags on every page (via the config overlay defaults)
Feed and sitemap removal — prevents content leakage through structured formats. The sed step also strips tags from the HTML so there’s no discoverable feed URL even in the page source.

Binary Artifact Filtering

- name: Remove oversized binaries from deploy output
  run: |
    rm -rf _site/assets/exes
    find _site -type f \( -iname '*.exe' -o -iname '*.msi' \) -print -delete
    find _site -type f -size +45M -print -delete

The production site has some downloadable executables under assets/exes/. These triggered GitHub large-file warnings during deployment and aren’t needed for draft review. The 45MB guard catches anything else that shouldn’t be in a static site deployment.

Cross-Repo Deploy

- name: Deploy to drafts.mcgarrah.org repo
  run: |
    deploy_dir="$(mktemp -d)"
    git clone --depth 1 --branch main \
      "https://x-access-token:${DRAFTS_DEPLOY_TOKEN}@github.com/${TARGET_REPO}.git" \
      "$deploy_dir"

    find "$deploy_dir" -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +
    cp -a _site/. "$deploy_dir"/

    echo "drafts.mcgarrah.org" > "$deploy_dir/CNAME"
    touch "$deploy_dir/.nojekyll"

    cd "$deploy_dir"
    git add -A
    if git diff --cached --quiet; then
      echo "No drafts-site changes to deploy"
      exit 0
    fi

    git commit -m "Deploy drafts site from ${GITHUB_SHA}"
    git push origin HEAD:main --force-with-lease

A few details worth noting:

The .nojekyll file prevents GitHub Pages from re-processing the already-built HTML through Jekyll again
--force-with-lease is safer than --force — it fails if someone else pushed to the drafts repo since the clone, rather than silently overwriting
The git diff --cached --quiet check skips the push entirely if nothing changed, avoiding empty commits
The shallow clone (--depth 1) keeps the operation fast since we don’t need history

Staticrypt Testing Results

What works:

Draft and future post pages present the Staticrypt password prompt as expected
The --remember 30 flag stores the decryption key in localStorage — after entering the password once, subsequent pages decrypt automatically without re-prompting
The encrypted HTML contains the Staticrypt wrapper, verified by both hash comparison and string detection in CI
The custom template title (“Draft Preview - mcgarrah.org”) makes it clear which site you’re on even at the password prompt

What needs more testing before broad reviewer rollout:

Cross-browser --remember behavior over longer sessions (does it survive browser updates?)
Mobile UX around the password prompt and navigation flow
Private/incognito windows (should always prompt — localStorage is session-scoped in incognito)

Giscus Feedback

Giscus is configured to point at the drafts.mcgarrah.org repo’s Discussions with a dedicated “Draft Reviews” category. This keeps preview feedback completely separate from production comments.

The Giscus