While that prevents the standard 404 error when a desktop browser requests the icon, it completely ignores the modern web. Mobile devices, tablets, and modern browsers expect high-resolution PNGs, Apple Touch icons, and web manifests. Without them, users bookmarking the site to their home screens get a generic, ugly letter block instead of a proper logo.

It was sitting on my internal TODO.md as a “Quick Win” for far too long. Here is how I finally fixed it and implemented a modern favicon set.

“It’s the small things that matter. The details.” — The Twelfth Doctor

The Problem with Just favicon.ico

If you check your web server logs, you’ll likely see a stream of 404 errors for files you never created:

• /apple-touch-icon-precomposed.png
• /apple-touch-icon.png

iOS devices automatically request these files when a user adds your site to their home screen. Android devices look for an Android Chrome manifest. If they aren’t there, you get degraded UX and messy logs.

Here is the source image I started with — a TARDIS icon at 1067x1067 pixels with a solid white background:

Step 1: Generate the Assets

You have two choices here. I went with the CLI route because I wanted control over the transparency — the web generators do not offer that option — and because I am a UNIX guy of old who is perfectly comfortable in a terminal. That said, if you just want a zip file of correctly sized icons without thinking about it, the web generator is the faster path.

Option A: The Fast Track (Web Generator)

If you do not need transparency or custom processing, this is the easiest route.

1. Start with a high-resolution version of your logo (ideally a square PNG or SVG, at least 260x260 pixels).
2. Go to RealFaviconGenerator.net.
3. Upload your image and configure the exact padding, background colors, and styling for iOS, Android, Windows Metro, and macOS Safari pinned tabs.
4. Generate and download the resulting .zip package.

Option B: The Local CLI Route (ImageMagick)

This is the route I took. If you want full control over the output — especially transparency — ImageMagick gives you that. Assuming your source image is logo.png:

Optional: Make the background transparent

If your source image has a solid background (like white) and you want it transparent, you can strip it out first. This is the main reason I chose the CLI route — none of the web generators I found offered this.

The trick is the fuzz factor. A naive -transparent white only removes exact #FFFFFF pixels and misses the slightly blended, anti-aliased pixels at the edges of the logo, leaving a visible white halo. I started at 5% and it still had noticeable halo artifacts, so I bumped it 5% at a time until 10% produced a clean result:

convert logo.png -fuzz 10% -transparent white transparent-logo.png

Here is the result — the same icon after stripping the white background at 10% fuzz. The anti-aliased edges are clean with no visible halo:

(If you do this, just substitute transparent-logo.png for logo.png in the sizing commands below.)

Convert files

# Generate the Apple Touch icon
convert logo.png -resize 180x180 apple-touch-icon.png

# Generate the standard PNG favicons
convert logo.png -resize 32x32 favicon-32x32.png
convert logo.png -resize 16x16 favicon-16x16.png

# Combine them into a multi-resolution favicon.ico
convert favicon-16x16.png favicon-32x32.png favicon.ico

# Generate Android Chrome icons for the manifest
convert logo.png -resize 192x192 favicon-192x192.png
convert logo.png -resize 512x512 favicon-512x512.png

You will also need to manually create the site.webmanifest JSON file to register your Android icons:

{
  "name": "McGarrah Technical Blog",
  "short_name": "McGarrah",
  "icons": [
    { "src": "/favicon-192x192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/favicon-512x512.png", "sizes": "512x512", "type": "image/png" }
  ],
  "theme_color": "#ffffff",
  "background_color": "#ffffff",
  "display": "standalone"
}

Step 2: Add Files to the Jekyll Root

If you used the web generator, extract the .zip directly into your Jekyll project’s root directory. If you used ImageMagick, move the generated files there along with your hand-written site.webmanifest. Either way, you should end up with a collection of files including:

• apple-touch-icon.png (180x180)
• favicon-32x32.png
• favicon-16x16.png
• site.webmanifest
• favicon.ico

Note: It’s important to keep these at the root level (/), as many tools and legacy browsers request them from the root by default without parsing your HTML.

Step 3: Update the HTML Head

The web generator provides a block of HTML to paste into your site. In a standard Jekyll setup, this goes into _includes/head.html or directly inside the <head> block of _layouts/default.html. If you took the ImageMagick route, the block below is what you need.

To ensure the links work regardless of environment or subdirectories, use Jekyll’s relative_url filter. I added this block just before the closing </head> tag:

<!-- Favicons -->
<link rel="apple-touch-icon" sizes="180x180" href="{{ '/apple-touch-icon.png' | relative_url }}">
<link rel="icon" type="image/png" sizes="32x32" href="{{ '/favicon-32x32.png' | relative_url }}">
<link rel="icon" type="image/png" sizes="16x16" href="{{ '/favicon-16x16.png' | relative_url }}">
<link rel="manifest" href="{{ '/site.webmanifest' | relative_url }}">
<link rel="shortcut icon" href="{{ '/favicon.ico' | relative_url }}">
<meta name="theme-color" content="#ffffff">

Using relative_url ensures that if I ever preview the site in a sub-path or change domains, the asset links won’t break.

Testing Locally Before Pushing

Before pushing any of this to GitHub Pages, I tested it locally with bundle exec jekyll serve several times. Favicons are notoriously sticky in browser caches, so I made a habit of hard-refreshing (Ctrl+Shift+R) and checking the Network tab in DevTools to confirm the browser was actually fetching the new assets instead of serving stale ones.

Beyond the icons themselves, I verified that the HTML changes in _layouts/default.html were rendering correctly by viewing the page source and confirming all six <link> tags appeared in the <head>. I also hit http://localhost:4000/site.webmanifest directly in the browser to make sure Jekyll was serving the manifest file and that the JSON was valid with the correct icon paths. A missing or malformed manifest is silent — no errors in the console, just a broken “Add to Home Screen” experience that you would never notice without checking.

The transparency fuzz factor was the main thing I iterated on locally. Each time I regenerated the PNGs with a different percentage, I restarted Jekyll and checked the Apple Touch icon at 180x180 to see if the halo was gone. That feedback loop — regenerate, restart, hard-refresh — is much faster against a local server than waiting for a GitHub Pages deploy.

Once everything looked right locally, I pushed to GitHub and verified on the live site at mcgarrah.org. The deploy picked it up on the next build and the icons rendered identically to what I saw in local testing.

The Result

The whole process took about thirty minutes of actual work, spread across an hour of wall time because I was multitasking. Most of that was the local iteration on ImageMagick transparency — the favicon generation and HTML changes themselves were genuinely quick. After deploying, the stream of /apple-touch-icon.png 404 errors in my server logs disappeared immediately. More importantly, bookmarking the site to an iPhone home screen now shows my actual logo instead of a generic gray letter “M” in a rounded square.

Here is the final set of generated icons at their actual sizes, from the 512x512 Android Chrome icon down to the 16x16 browser tab favicon:

Icon	Size	Preview
favicon-512x512.png	512x512
favicon-192x192.png	192x192
apple-touch-icon.png	180x180
favicon-32x32.png	32x32
favicon-16x16.png	16x16

If you have a Jekyll site with just a bare favicon.ico, check your logs — you are almost certainly serving 404s for assets that mobile devices expect to exist. A few generated PNGs and six lines of HTML in your layout is all it takes to fix it.

My resume site runs as a sub-path off the same domain, so it picks up the root-level favicon assets automatically. Its Jekyll theme has its own _includes/head.html, which needed the same <link> block added, but the image files are shared. If you run multiple Jekyll projects under one domain, that is one less thing to duplicate.

“Never ignore the little things. In the whole wide universe, the little things are the most important.” — The Eleventh Doctor

Gallifreyan script generated with the Gallifreyan Translation Helper.

Most Jekyll blogs on GitHub Pages use the default build. Push to main, GitHub builds it, done. That worked for me too — until I needed custom plugins, scheduled future posts, and wanted to stop deploying broken sitemaps.

Here’s how it all fits together.

The Pipeline at a Glance

graph LR
    A[git push to main] --> B[Jekyll Build & Deploy]
    A --> C[CodeQL Security Scan]
    A --> D[SEO Health Check]
    E[Daily 10:05 UTC] --> B
    F[Weekly Friday 02:43 UTC] --> C
    G[Weekly Monday 06:00 UTC] --> D
    H[Dependabot] --> I[PRs for dependency updates]
    I --> A

Workflow 1: Build and Deploy

This is the core workflow. It replaced the default GitHub Pages build in August 2024 when I needed custom plugins that aren’t in the GitHub Pages whitelist.

name: Deploy Jekyll site to Pages

on:
  push:
    branches: ["main"]
  schedule:
    - cron: '5 10 * * *'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

Why a Custom Build?

The default GitHub Pages Jekyll build is convenient but limiting:

• No custom plugins — Only whitelisted gems run. My tag/category generator and Pandoc exports plugin need a custom build.
• No Ruby version pinning — GitHub controls the Ruby version. I pin to 3.2.6 for reproducibility.
• No build validation — The default build deploys whatever Jekyll produces. I validate the sitemap before deploying.

Scheduled Builds for Future Posts

The schedule trigger is the key feature that makes future-dated posts work:

schedule:
  - cron: '5 10 * * *'  # 10:05 UTC daily (6:05 AM EDT)

See GitHub’s scheduled events documentation for cron syntax details.

Jekyll’s future: false setting (the default) excludes posts with dates in the future from the build output. When a post’s date arrives, the next build picks it up. The daily cron at 10:05 UTC (6:05 AM EDT) means a post dated 2026-05-15 will go live within 24 hours of that date — close enough for a blog.

Without this, I’d have to manually push a commit or trigger a build on the day I want a post to go live.

The --future Flag Gotcha

During local development, bundle exec jekyll serve also respects future: false — future-dated posts won’t render locally unless you add the --future flag:

bundle exec jekyll serve --future

This confused me early on. I’d write a post with tomorrow’s date, run the local server, and the post wouldn’t appear. The future: false config setting only controls the build output, not whether the file is recognized. The --future flag overrides it for local previewing. In production, the daily cron handles it — you never need future: true in _config.yml.

Sitemap Validation

After discovering that a bad build once deployed a sitemap full of localhost URLs, I added a pre-deploy validation step:

- name: Validate sitemap URLs
  run: |
    if grep -q 'localhost' ./_site/sitemap.xml; then
      echo "::error::sitemap.xml contains localhost URLs"
      grep 'localhost' ./_site/sitemap.xml | head -5
      exit 1
    fi
    echo "Sitemap OK: all URLs use production domain"

This is a cheap check that has saved me at least once. The JEKYLL_ENV: production environment variable is also critical — without it, Jekyll may use development URLs.

Build Steps

The full build job:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: ruby/setup-ruby@v1.300.0
        with:
          ruby-version: '3.2.6'
          bundler-cache: true
          cache-version: 1
      - uses: actions/configure-pages@v6
      - name: Build with Jekyll
        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
        env:
          JEKYLL_ENV: production
      - name: Validate sitemap URLs
        run: |
          if grep -q 'localhost' ./_site/sitemap.xml; then
            echo "::error::sitemap.xml contains localhost URLs"
            exit 1
          fi
      - uses: actions/upload-pages-artifact@v4

Key details:

• bundler-cache: true — Caches installed gems between runs. Cuts build time significantly.
• cache-version: 1 — Increment this to force a fresh gem install if the cache gets corrupted.
• configure-pages — Sets the base path for GitHub Pages. Required for correct URL generation.
• cancel-in-progress: false — Don’t cancel a running deployment if a new push arrives. Let it finish.

Evolution

The build workflow has been through nine commits since August 2024:

1. Aug 2024 — Initial creation, replacing default GitHub Pages build
2. Jan 2025 — Ruby version updates and deploy comments
3. May 2025 — Fix caching issues during build
4. Sep 2025 — Add scheduled daily builds for future posts
5. Sep 2025 — Dependabot bumps for checkout and upload-pages-artifact
6. Apr 2026 — Add sitemap localhost validation
7. Apr 2026 — Update all actions to Node 24 compatible versions

Workflow 2: CodeQL Security Scanning

name: "CodeQL Advanced"

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  schedule:
    - cron: '43 2 * * 5'  # Weekly Friday at 02:43 UTC

What Does CodeQL Scan on a Jekyll Blog?

Not much, honestly. The initial setup in September 2025 included Ruby and JavaScript language analysis, but those were removed the same day — CodeQL’s Ruby analysis isn’t useful for Jekyll plugins (they’re too simple), and the JavaScript is mostly CDN-loaded.

What remains is GitHub Actions workflow analysis (language: actions), which scans the workflow YAML files themselves for security issues like:

• Untrusted input in run steps
• Missing permission restrictions
• Vulnerable action versions
• Script injection via ${{ }} expressions

strategy:
  fail-fast: false
  matrix:
    include:
    - language: actions
      build-mode: none

Is It Worth It?

For a static blog? Marginally. The Actions language scanner has caught zero issues so far. But it’s free, runs weekly, and takes under a minute. The real value is that it’s already configured — if I add more complex JavaScript or Ruby in the future, I can re-enable those language scanners with one line change.

Workflow 3: SEO Health Check

This is the most complex workflow and has its own dedicated article. Here’s the summary of what it validates on every content push and weekly:

Triggers

on:
  schedule:
    - cron: '0 6 * * 1'  # Weekly Monday at 6 AM UTC
  workflow_dispatch:
  push:
    branches: [main]
    paths:
      - '_config.yml'
      - '_layouts/**'
      - '_includes/**'
      - '_plugins/**'
      - '_posts/**'
      - '_sass/**'
      - 'assets/**'
      - 'robots.txt'
      - '.github/workflows/seo-health-check.yml'
      - '.lighthouserc.json'

The paths filter is important — this workflow only runs on pushes that change content or configuration, not on README edits or draft changes. This saves CI minutes.

What It Checks

The workflow builds the site, serves it locally, then runs a gauntlet of checks:

1. Lighthouse CI — Performance (≥0.8), accessibility (≥0.9), best practices (≥0.8), SEO (≥0.9 — hard fail). Runs 3 times per URL and averages. Blocks AdSense and Analytics scripts to get clean scores.
2. Canonical URL consistency — Every <link rel="canonical"> tag must use mcgarrah.org
3. Sitemap validation — Valid XML, correct domain, no www prefix
4. Sitemap index validation — References both blog and resume sitemaps
5. Robots.txt — Exists, references correct sitemap index
6. Meta tags — Description and Open Graph tags on homepage
7. RSS feed — Valid XML
8. Link checking — Lychee for broken links across all HTML
9. Structured data — JSON-LD presence
10. Image optimization — Missing alt text, oversized images (>500KB)
11. Content quality — Duplicate titles, duplicate meta descriptions, generic link text (“click here”, “read more”)
12. Mobile optimization — Viewport meta tag coverage
13. Accessibility indicators — Invalid anchors, small tap targets

Lighthouse Configuration

The .lighthouserc.json blocks ad and analytics scripts to get clean performance scores:

{
  "ci": {
    "collect": {
      "numberOfRuns": 3,
      "settings": {
        "blockedUrlPatterns": [
          "**/pagead/js/adsbygoogle.js*",
          "**/googlesyndication.com/**",
          "**/googletagmanager.com/**"
        ]
      }
    },
    "assert": {
      "assertions": {
        "categories:performance": ["warn", {"minScore": 0.8}],
        "categories:accessibility": ["warn", {"minScore": 0.9}],
        "categories:seo": ["error", {"minScore": 0.9}]
      }
    }
  }
}

SEO is the only hard fail (error). Performance and accessibility are warnings — I want to know about regressions but don’t want to block deploys over a 0.79 performance score.

The Canonical URL Bug

The SEO health check went through five rapid-fire commits on April 8, 2026 — all fixing the same class of problem. The canonical URL check was matching mcgarrah.org in blog post content (syntax-highlighted code examples), not just in <link> tags. The fix narrowed the grep to match only actual <link rel="canonical"> tags:

find _site -name "*.html" -exec grep -h '<link[^>]*rel="canonical"' {} \;

Lesson: when your blog posts contain code examples about your own blog’s configuration, your CI checks will match the examples. Always be specific in your grep patterns.

Dependabot

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "."
    schedule:
      interval: "daily"
  - package-ecosystem: "bundler"
    directory: "./"
    schedule:
      interval: "daily"
  - package-ecosystem: "npm"
    directory: "./"
    schedule:
      interval: "weekly"

Three ecosystems, three schedules:

• GitHub Actions (daily) — Catches action version bumps quickly. These are the most security-sensitive since they run with repo permissions.
• Bundler (daily) — Jekyll and Ruby gem updates. The Gemfile.lock pins exact versions.
• npm (weekly) — Tracks CDN library versions in package.json for security scanning, even though the actual libraries load from CDN at runtime. See the security dependency management post for why.

Dependabot creates PRs automatically. Each PR triggers the build and CodeQL workflows, so I get a test build before merging.

How the Pieces Interact

The workflows aren’t isolated — they form a feedback loop:

1. Dependabot creates a PR to bump actions/checkout from v5 to v6
2. The PR triggers CodeQL (scans the updated workflow YAML) and Build (tests the build with the new action version)
3. I merge the PR → push to main
4. Push triggers all three workflows: Build deploys, CodeQL scans, SEO Health Check validates
5. If the SEO check finds a regression (broken link, missing meta tag), I fix it and push again

The daily cron on the build workflow handles future-dated posts without any manual intervention. The weekly crons on CodeQL and SEO catch drift — a dependency that introduced a vulnerability, or an external link that went dead.

Cost

All of this runs on GitHub’s free tier for public repositories. The monthly usage is minimal:

• Build & Deploy: ~30 runs/month (daily cron + pushes), ~2 min each
• CodeQL: ~8 runs/month (weekly + pushes), ~1 min each
• SEO Health Check: ~12 runs/month (weekly + content pushes), ~4 min each
• Total: ~100 minutes/month, well within the 2,000 free minutes

What I’d Add Next

• HTML-Proofer — More thorough internal link validation than my custom script
• Pa11y — Automated accessibility testing beyond Lighthouse
• Build time tracking — Alert if build time exceeds a threshold (currently ~90 seconds)
• Deployment notifications — Slack or email on successful deploy of future-dated posts

Related Posts

• Advanced Jekyll SEO Health Checks — Deep dive into the SEO workflow
• Building This Blog: Jekyll on GitHub Pages — Setup guide with CI/CD overview
• Using GitHub Actions with pip-audit — Similar CI pattern for Python projects
• Building a Custom Tag and Category Generator Plugin — One of the custom plugins that requires this pipeline
• Your Jekyll Sitemap Is 60% Garbage — The sitemap problem that led to the validation step
• How the Sausage Is Made — Full feature inventory
• Ruby Gem Release Automation — CI/CD for the Pandoc exports gem

But comments need state. Someone writes a comment, it has to be stored somewhere, and the next visitor needs to see it. Adding state to a stateless platform is a fundamental design tension — you need a data store, but you chose a platform specifically because it doesn’t have one.

The Problem

I wanted comments on this blog for a simple reason: readers ask good questions. When someone finds a gap in a Proxmox walkthrough or catches an error in a Ceph command, that feedback is valuable — not just to me, but to the next person reading the same post. Email works for one-to-one, but comments are one-to-many.

The requirements:

1. No self-hosted infrastructure — I’m not running a database for blog comments
2. Free or very cheap — This is a hobby blog
3. GitHub-friendly — My readers are technical; most have GitHub accounts
4. GDPR-compatible — No third-party tracking cookies
5. Persistent — Comments survive site rebuilds and theme changes
6. Searchable — Ideally indexed and findable
7. Low maintenance — No moderation queue to babysit

The Alternatives I Evaluated

Disqus — The Default Choice (Rejected)

Disqus is the most common comment system for static sites. It’s easy to embed and has a large user base.

Why I rejected it:

• Ads on the free tier — Disqus injects ads into your comment section unless you pay
• Tracking and privacy — Disqus loads significant third-party JavaScript and tracks users across sites. This is a GDPR nightmare for a blog that already went through extensive GDPR compliance work
• Data ownership — Comments live on Disqus’s servers. If they shut down or change terms, your comments are gone
• Heavy JavaScript — The embed script is large and slows page load

The original Jekyll theme I forked (Contrast) actually had Disqus support built in. The dead code is still in my post.html layout — a disqus_thread div that never renders because site.comments.disqus_shortname is never set.

Isso — Self-Hosted Alternative (Rejected)

Isso is a self-hosted, lightweight commenting server. It stores comments in a SQLite database and has a clean, minimal interface.

Why I rejected it:

• Requires a server — You need to run the Isso daemon somewhere. That’s infrastructure I don’t want to maintain for blog comments
• SQLite on a server — Backups, uptime, security patches — all for a comment system

The theme also had Isso support built in. Same dead code situation — isso_domain is never configured.

GitHub Issues API — Custom Lambda (Evaluated Deeply)

This approach uses GitHub Issues as the comment store. Each blog post maps to a GitHub Issue. Comments on the Issue appear as comments on the post. Aleksandr Hovhannisyan’s implementation is the best-known version.

I went deep on this one — deep enough to have ChatGPT convert the original Netlify serverless function to a Python Lambda. The full prototype:

def get_comments_for_post(event, context):
    """
    Lambda function to fetch comments for a GitHub issue dynamically.
    """

    try:
        # Extract query parameters
        query_params = event.get("queryStringParameters", {})
        issue_number = query_params.get("id")
        github_url = query_params.get("url")

        if not issue_number or not issue_number.isdigit():
            return {
                "statusCode": 400,
                "body": json.dumps({"error": "You must specify a valid issue ID."}),
            }

        # Determine owner and repo
        if github_url:
            owner, repo = extract_owner_and_repo(github_url)
        else:
            owner = query_params.get("owner")
            repo = query_params.get("repo")

        if not owner or not repo:
            return {
                "statusCode": 400,
                "body": json.dumps({"error": "You must specify 'owner' and 'repo' or provide a valid GitHub URL."}),
            }

        issue_number = int(issue_number)

        # Check API rate limit
        rate_limit = octokit.request("GET /rate_limit")["rate"]
        remaining_requests = rate_limit["remaining"]
        print(f"GitHub API requests remaining: {remaining_requests}")
        if remaining_requests == 0:
            return {
                "statusCode": 503,
                "body": json.dumps({"error": "API rate limit exceeded."}),
            }

        # Fetch comments for the given issue
        comments_response = octokit.paginate(
            "GET /repos/{owner}/{repo}/issues/{issue_number}/comments",
            {"owner": owner, "repo": repo, "issue_number": issue_number},
        )

        # Process comments
        response = []
        for comment in comments_response:
            response.append({
                "user": {
                    "avatarUrl": comment["user"]["avatar_url"],
                    "name": escape(comment["user"]["login"]),
                    "isAuthor": comment["author_association"] == "OWNER",
                },
                "dateTime": comment["created_at"],
                "dateRelative": str((datetime.now() - datetime.fromisoformat(
                    comment["created_at"].replace("Z", ""))).days) + " days ago",
                "isEdited": comment["created_at"] != comment["updated_at"],
                "body": escape(markdown(comment["body"])),
            })

        return {
            "statusCode": 200,
            "body": json.dumps({"data": response}),
        }

    except Exception as e:
        print(f"Error: {e}")
        return {
            "statusCode": 500,
            "body": json.dumps({"error": "Unable to fetch comments for this post."}),
        }

This prototype handled input validation, GitHub API rate limiting, pagination, relative date formatting, edit detection, and Markdown rendering. It worked — but it was a lot of moving parts for blog comments.

Why I ultimately rejected it:

• Requires a serverless function — Whether it’s Netlify Functions, AWS Lambda, or Cloudflare Workers, you need a backend to proxy the GitHub API (to avoid exposing tokens client-side)
• GitHub Issues aren’t designed for comments — Issues have a flat structure. No threading, no reactions on individual comments (only on the issue itself)
• Manual issue creation — You have to create a GitHub Issue for each post and link them. That’s a maintenance burden
• API rate limits — The GitHub API has rate limits that could be hit on popular posts

Utterances — GitHub Issues, Client-Side (Close Second)

Utterances solves the serverless function problem by using a GitHub App to authenticate directly from the client. It still uses GitHub Issues as the backend but doesn’t need a proxy.

Why I almost chose it:

• No server needed — just a <script> tag
• Clean, minimal UI
• GitHub authentication (my audience has GitHub accounts)
• Open source

Why I chose Giscus instead:

• Utterances uses Issues, Giscus uses Discussions — Discussions have threading, categories, and reactions
• Utterances was less actively maintained at the time I evaluated it
• Giscus is essentially “Utterances but better” — same concept, newer implementation, more features

Staticman — Git-Based Comments (Rejected)

Staticman takes a different approach: comments are submitted via a form, processed by a bot, and committed to your repository as data files (YAML/JSON). Jekyll then renders them at build time.

Why I rejected it:

• Build required for every comment — Each comment triggers a site rebuild. That’s slow and burns CI minutes
• Moderation via pull requests — Clever, but adds friction
• Self-hosted bot or shared instance — The shared instance has availability issues; self-hosting is more infrastructure

GDPR-Compliant Approaches

The Jekyll Codex GDPR-compliant comments guide was useful for understanding the privacy landscape. Any solution that loads third-party JavaScript or sends user data to external servers needs consent management.

Why Giscus Won

Giscus uses GitHub Discussions as the comment backend. It’s a single <script> tag that embeds a widget powered by the GitHub Discussions API via a GitHub App.

The key insight: everything stays in the GitHub ecosystem. The blog source is on GitHub. The build runs on GitHub Actions. The site deploys to GitHub Pages. Comments live in GitHub Discussions. There’s no external service, no separate database, no additional account.

What sealed the decision:

• Threaded replies — Discussions support nested replies, Issues don’t
• Reactions — Readers can react to individual comments, not just the top-level post
• Categories — Comments go into the “Announcements” category, keeping them organized
• Automatic mapping — pathname mapping means Giscus creates a Discussion for each post URL automatically. No manual issue creation
• Lazy loading — The widget loads only when scrolled into view (loading: lazy)
• Theme matching — preferred_color_scheme follows the reader’s dark/light mode preference
• Searchable — GitHub Discussions are fully searchable, both on GitHub and via search engines
• No server — Just a <script> tag and a _config.yml entry
• GDPR-friendly — Giscus loads from giscus.app (a GitHub App), not a third-party ad network. No tracking cookies. The self-hosting option exists if you want full control

Implementation

Step 1: Enable GitHub Discussions

In the repository settings (mcgarrah/mcgarrah.github.io), enable the Discussions feature and create an “Announcements” category.

Step 2: Install the Giscus GitHub App

Go to giscus.app, select your repository, and configure the options. It generates the <script> tag and gives you the repo_id and category_id values.

Step 3: Add Configuration to _config.yml

giscus:
  repo: mcgarrah/mcgarrah.github.io
  repo_id: R_kgDOKBKIdw
  category: Announcements
  category_id: DIC_kwDOKBKId84Cq3DK
  mapping: pathname
  strict: 0
  reactions_enabled: 1
  emit_metadata: 0
  input_position: bottom
  theme: preferred_color_scheme
  lang: en
  loading: lazy

Key configuration choices:

• mapping: pathname — Maps posts to Discussions by URL path. This means /proxmox-ceph-nearfull/ gets its own Discussion automatically
• strict: 0 — Fuzzy matching on the pathname. Tolerates minor URL changes
• input_position: bottom — Comment box below existing comments (natural reading order)
• loading: lazy — Don’t load the iframe until the reader scrolls to the comments section. Improves initial page load performance
• theme: preferred_color_scheme — Matches the reader’s OS dark/light mode setting

Step 4: Add the Widget to the Post Layout

In _layouts/post.html:

{%- if site.giscus -%}
<section class="page__comments">
  <script src="https://giscus.app/client.js"
          data-repo="{{ site.giscus.repo }}"
          data-repo-id="{{ site.giscus.repo_id }}"
          data-category="{{ site.giscus.category }}"
          data-category-id="{{ site.giscus.category_id }}"
          data-mapping="{{ site.giscus.mapping }}"
          data-strict="{{ site.giscus.strict }}"
          data-reactions-enabled="{{ site.giscus.reactions_enabled }}"
          data-emit-metadata="{{ site.giscus.emit_metadata }}"
          data-input-position="{{ site.giscus.input_position }}"
          data-theme="{{ site.giscus.theme }}"
          data-lang="{{ site.giscus.lang }}"
          data-loading="{{ site.giscus.loading }}"
          crossorigin="anonymous"
          async>
  </script>
</section>
{%- endif -%}

Every _config.yml value is templated via Liquid — no hardcoded values in the layout. The {%- if site.giscus -%} guard means the widget only renders if Giscus is configured, so the theme works without it.

Legacy Dead Code

The post layout still contains the original theme’s Isso and Disqus support:

{% if page.comments != false and site.comments.isso or site.comments.disqus %}
  {% if site.comments.isso_domain %}<div id="isso-thread"></div>{% endif %}
  {% if site.comments.disqus_shortname %}<div id="disqus_thread"></div>{% endif %}
{% endif %}

This never renders because neither site.comments.isso_domain nor site.comments.disqus_shortname is set in _config.yml. It’s harmless dead code from the Contrast theme fork. I’ve left it in case someone forks this blog and wants to use those systems instead.

The GitHub Ecosystem Advantage

What I find elegant about this setup is how the pieces reinforce each other:

Everything is in one place. One login, one set of permissions, one backup strategy (the git repository itself). If GitHub goes down, the whole blog is down anyway — there’s no additional point of failure from the comment system.

Comments are also version-controlled in a sense — GitHub Discussions have full edit history, and they’re tied to the repository. If I ever migrate the blog, the Discussions come with the repo.

The broader pattern here is worth noting: keeping your entire operational surface area in a single ecosystem — source, build, hosting, comments, security scanning, dependency management — reduces the number of vendor relationships, authentication boundaries, and failure domains you have to manage. It’s the same principle behind choosing a single cloud provider for tightly coupled services.

What I’d Do Differently

• Clean up the dead Isso/Disqus code — It’s been there since the fork. Time to remove it
• Add a comments: false front matter option — The Isso/Disqus code checks page.comments != false, but the Giscus block doesn’t. Some posts (like the privacy policy) shouldn’t have comments
• Consider self-hosting Giscus — The self-hosting guide would eliminate the dependency on giscus.app. Low priority since the service has been reliable

Related Posts

• Building This Blog: Jekyll on GitHub Pages — Setup guide with brief Giscus section
• How the Sausage Is Made — Feature inventory including comments
• Implementing GDPR Compliance for Jekyll with AdSense — The GDPR work that informed comment system requirements
• The CI/CD Pipeline Behind This Jekyll Blog — How GitHub Actions ties into the ecosystem

GitHub Pages with Jekyll gives you tags and categories in front matter, but no pages for them. You can tag a post proxmox all day long — there’s no /tags/proxmox/ page unless you build one. Manually creating a page for each tag doesn’t scale. This plugin solves it: a single Ruby file that generates a page for every tag and every category at build time.

The Problem

Jekyll’s built-in site.tags and site.categories hashes collect posts by taxonomy, but they don’t generate browsable pages. Most Jekyll themes include a tags.html that lists all tags on one page, but clicking a tag doesn’t go anywhere useful.

The common solutions are:

1. Manual pages — Create a markdown file per tag. Doesn’t scale.
2. Third-party plugins — jekyll-tagging, jekyll-archives. Not whitelisted on GitHub Pages (if using the default build).
3. Custom generator plugin — Write your own. Works with GitHub Actions builds.

Useful references I consulted during the decision:

• Long Qian’s Jekyll tag page guide — The approach I adapted
• Untangled.dev tag management — Alternative approach
• Jekyll docs on tags — Official reference

I went with option 3 because I was already using GitHub Actions for the build (required for other custom plugins), and I wanted full control over URL structure and SEO behavior.

Evolution of the Plugin

The plugin went through three distinct versions, each driven by a real problem. The git history tells the story.

Version 1: Basic Generator (July 2025)

The initial version was straightforward — two Generator classes and two Page classes. It iterated site.tags and site.categories, created a page for each, and was done:

module Jekyll
  class TagPageGenerator < Generator
    safe true

    def generate(site)
      site.tags.each do |tag, posts|
        site.pages << TagPage.new(site, site.source, tag, posts)
      end
    end
  end

  # ... CategoryPageGenerator identical pattern ...

  class TagPage < Page
    def initialize(site, base, tag, posts)
      @site = site
      @base = base
      @dir = File.join('tags', tag.downcase.gsub(' ', '-'))
      @name = 'index.html'

      self.process(@name)
      self.read_yaml(File.join(base, '_layouts'), 'tag_page.html')
      self.data['tag'] = tag
      self.data['posts'] = posts
      self.data['title'] = "Posts tagged with \"#{tag}\""
    end
  end
end

This worked fine for months. Then AdSense review forced a closer look at the sitemap.

Version 2: Sitemap Exclusion and Noindex (April 6, 2026 — morning)

During AdSense review preparation, I audited the sitemap and found it had 434 URLs, 262 of which (60%) were auto-generated tag, category, and pagination pages with little unique content. This dilutes content quality signals.

The fix added two lines to each Page class and a Jekyll::Hooks callback for pagination:

# Added to TagPage and CategoryPage:
self.data['sitemap'] = false
self.data['noindex'] = true if posts.size < 3

# Added for pagination pages:
Jekyll::Hooks.register :pages, :post_init do |page|
  if page.url =~ %r{^/page\d+/}
    page.data['sitemap'] = false
  end
end

Result: sitemap dropped from 434 to 172 URLs. 195 thin tag/category pages got noindex.

Version 3: Hook-to-Generator Refactor (April 6, 2026 — afternoon)

The Jekyll::Hooks :pages :post_init approach broke pagination within hours. The hook fired during page initialization — before jekyll-paginate had created its pagination pages. This caused the homepage to display as page 32 of 32 (oldest posts first) and prevented pagination directories from being created.

The fix replaced the hook with a lowest-priority Generator that runs after jekyll-paginate has finished:

class PaginationSitemapExcluder < Generator
  safe true
  priority :lowest

  def generate(site)
    site.pages.each do |page|
      if page.dir =~ %r{^/page\d+}
        page.data['sitemap'] = false
      end
    end
  end
end

The key insight: priority :lowest ensures this generator runs after all other generators (including jekyll-paginate), so the pagination pages exist by the time we iterate them. The hook approach was too early in the lifecycle.

Result: homepage showed newest posts again (page 1 of 32), all 31 pagination directories restored, pagination pages still excluded from sitemap.

The Final Plugin

The current version lives in _plugins/tag_category_generator.rb:

module Jekyll
  class TagPageGenerator < Generator
    safe true

    def generate(site)
      site.tags.each do |tag, posts|
        site.pages << TagPage.new(site, site.source, tag, posts)
      end
    end
  end

  class CategoryPageGenerator < Generator
    safe true

    def generate(site)
      site.categories.each do |category, posts|
        site.pages << CategoryPage.new(site, site.source, category, posts)
      end
    end
  end

  class TagPage < Page
    def initialize(site, base, tag, posts)
      @site = site
      @base = base
      @dir = File.join('tags', tag.downcase.gsub(' ', '-'))
      @name = 'index.html'

      self.process(@name)
      self.read_yaml(File.join(base, '_layouts'), 'tag_page.html')
      self.data['tag'] = tag
      self.data['posts'] = posts
      self.data['title'] = "Posts tagged with \"#{tag}\""
      self.data['sitemap'] = false
      self.data['noindex'] = true if posts.size < 3
    end
  end

  class CategoryPage < Page
    def initialize(site, base, category, posts)
      @site = site
      @base = base
      @dir = File.join('categories', category.downcase.gsub(' ', '-').gsub('_', '-'))
      @name = 'index.html'

      self.process(@name)
      self.read_yaml(File.join(base, '_layouts'), 'category_page.html')
      self.data['category'] = category
      self.data['posts'] = posts
      self.data['title'] = "Posts in category \"#{category}\""
      self.data['sitemap'] = false
      self.data['noindex'] = true if posts.size < 3
    end
  end

  class PaginationSitemapExcluder < Generator
    safe true
    priority :lowest

    def generate(site)
      site.pages.each do |page|
        if page.dir =~ %r{^/page\d+}
          page.data['sitemap'] = false
        end
      end
    end
  end
end

Design Decisions

safe true — Marks the generator as safe for GitHub Pages compatibility. Even though we’re building with GitHub Actions, this is good practice.

URL structure — Tags go to /tags/tag-name/ and categories to /categories/category-name/. The downcase.gsub(' ', '-') normalizes spaces to hyphens. Categories also convert underscores to hyphens for consistency.

sitemap: false — This was added after discovering that the generated pages were bloating the sitemap. With 237 tags, that’s 237 extra URLs in sitemap.xml — most pointing to pages with only one or two posts. See Your Jekyll Sitemap Is 60% Garbage for the full story.

noindex for thin content — Tags with fewer than 3 posts get noindex to avoid search engines indexing low-value pages. This is a soft SEO signal — the page still exists for users, but search engines are asked to skip it.

PaginationSitemapExcluder — A bonus generator that excludes /page2/, /page3/, etc. from the sitemap. These pagination pages add no SEO value and were another source of sitemap bloat. This was originally a Jekyll::Hooks :pages :post_init callback, but that broke jekyll-paginate because the hook fired before pagination pages existed. The priority :lowest Generator approach runs after all other generators have finished.

The Layouts

Both layouts are nearly identical. Here’s _layouts/tag_page.html:

---
layout: default
---

<article class="page">
  <h1 class="page-title">{{ page.title }}</h1>
  <div class="page-content">
    <div class="posts-list">
      {% for post in page.posts %}
        <article class="post-item">
          <h2><a href="{{ post.url | relative_url }}">{{ post.title }}</a></h2>
          <time datetime="{{ post.date | date_to_xmlschema }}">{{ post.date | date: site.date_format }}</time>
          {% if post.excerpt %}
            <div class="post-excerpt">{{ post.excerpt }}</div>
          {% endif %}
        </article>
      {% endfor %}
    </div>
  </div>
</article>

The category_page.html layout is identical. You could DRY this up with an include, but for two files it’s not worth the indirection.

The Index Pages

Users need a way to browse all tags and categories. These are simple Liquid pages:

tags.html:

---
layout: list_page
title: All Tags
---
<div class="taxonomies-list">
  {% for tag_hash in site.tags %}
    {% assign tag_name = tag_hash[0] %}
    {% assign num_posts = tag_hash[1].size %}
    <a href="{{ site.baseurl }}/tags/{{ tag_name | slugify }}/" class="taxonomy-item">
      {{ tag_name }} ({{ num_posts }})
    </a>
  {% endfor %}
</div>

categories.html follows the same pattern with site.categories.

GitHub Actions Requirement

This plugin won’t work with the default GitHub Pages Jekyll build — only whitelisted plugins run there. You need a GitHub Actions workflow that runs jekyll build yourself and deploys the output.

If you’re already using GitHub Actions for your Jekyll build (which you’ll need for any custom plugin), this just works — drop the .rb file in _plugins/ and it’s picked up automatically.

Lessons Learned

Tag proliferation is real. At 237 tags across 139 posts, many tags have only 1-2 posts. This creates thin content pages that dilute SEO. The noindex threshold helps, but the real fix is disciplined tagging — reuse existing tags rather than inventing new ones for every post.

Sitemap exclusion matters. The original version of this plugin didn’t set sitemap: false. The result was a sitemap with 434 URLs where 262 were auto-generated junk. Google Search Console flagged many as “Discovered – currently not indexed.” Adding sitemap: false cut the sitemap to meaningful content only.

Jekyll hook ordering is treacherous. The :post_init hook seemed like the right place to tag pagination pages for sitemap exclusion — it fires when a page is initialized. But jekyll-paginate creates pages during generation, not initialization. The hook fired too early, interfered with pagination’s template detection, and the homepage showed the oldest posts instead of the newest. The fix was moving to a priority :lowest Generator. Lesson: when modifying pages created by other plugins, use a Generator with lowest priority, not a hook.

Categories vs tags — In practice, categories on this blog are broad buckets (technical, homelab, web-development) while tags are specific topics (proxmox, ceph, jekyll). The plugin treats them identically but they serve different navigation purposes.

Current Stats

As of this writing:

• 139 published posts
• 237 unique tags → 237 generated tag pages
• 53 unique categories → 53 generated category pages
• Top tags: homelab (32), proxmox (23), jekyll (23), ceph (19), storage (18)
• Top categories: technical (63), homelab (22), web-development (21), hardware (20)

Related Posts

• Your Jekyll Sitemap Is 60% Garbage — The sitemap bloat problem this plugin caused and how it was fixed
• Building This Blog: Jekyll on GitHub Pages from Zero to 130+ Posts — Broader setup guide that mentions this plugin
• How the Sausage Is Made: Every Feature Powering This Jekyll Blog — Feature inventory including tag/category pages

Migration context: On May 1, 2026, AWS published the Amazon Q Developer end-of-support announcement. If you’re migrating from Amazon Q Developer to Kiro on Windows, WSL2 support is likely a hard requirement. This article covers exactly that gap.

The Open Remote - WSL extension by jeanp413 fills this gap. It’s a community-built, Open VSX-compatible implementation that enables WSL2 support in any VS Code fork, including Kiro. The Kiro GitHub issue #17 tracks the ongoing community experience — 38+ comments of workarounds, breakage reports, and fixes that inform everything in this article.

The extension works. It also breaks predictably on Kiro updates, has an easy-to-miss configuration requirement, and routes terminal commands to the wrong shell if you don’t set a default profile. None of these are dealbreakers, but they’ll cost you time if you don’t know about them going in.

The Problem

VS Code’s WSL integration is built on Microsoft’s proprietary Remote Development extensions. These extensions are:

• Licensed exclusively for use with Microsoft’s VS Code builds
• Published only to Microsoft’s Visual Studio Marketplace, not Open VSX
• Not available in Kiro’s extension marketplace

Without WSL support, Kiro on Windows can only access the Windows filesystem. Your Linux development environments, toolchains, and MCP servers running inside WSL2 are unreachable from the IDE. As multiple users in the tracking issue put it bluntly: Kiro is “completely useless” for Windows developers who do all their work inside WSL2.

Kiro itself acknowledges the gap — if you install the Linux version inside WSL2, it displays a message directing you to install the Windows version instead and use the remote extension approach.

Installation and the argv.json Requirement

Install the extension from Kiro’s extension panel or the command line:

kiro --install-extension jeanp413.open-remote-wsl

This is the step most people miss. The extension requires proposed API access to function. Without it, the extension installs silently but does nothing. Enable it in your ~/.kiro/argv.json file (or open it via the command palette: Preferences: Configure Runtime Arguments):

{
    "enable-proposed-api": [
        "jeanp413.open-remote-wsl"
    ]
}

Restart Kiro after making this change. If you have other entries in argv.json, add the enable-proposed-api array alongside them — don’t replace the file contents. If WSL commands don’t appear in the command palette after installing the extension, this missing configuration is almost certainly the reason.

After installation, the command palette gains WSL-specific commands:

• WSL: New Window — Open a new Kiro window connected to your default WSL distribution
• WSL: New Window using Distro... — Choose a specific distribution
• WSL: Open Folder in WSL... — Open a Linux folder directly
• WSL: Reopen Folder in WSL — Switch the current folder to WSL context

The Terminal Default Profile Gotcha

With the extension installed and a WSL2 folder open, Kiro’s agentic chat will attempt to run terminal commands. By default, it routes them to PowerShell — not the WSL terminal. This means commands that should execute in your Linux environment run in Windows instead, producing confusing failures.

The fix is to set the WSL distribution as your default terminal profile. Add this to your Kiro settings (%APPDATA%\Kiro\User\settings.json):

{
    "wsl.defaultDistro": "Ubuntu",
    "terminal.integrated.defaultProfile.windows": "WSL (Ubuntu)",
    "terminal.integrated.profiles.windows": {
        "WSL (Ubuntu)": {
            "path": "C:\\Windows\\System32\\wsl.exe",
            "args": ["-d", "Ubuntu"]
        }
    }
}

Replace Ubuntu with your distribution name. This ensures both manual terminal sessions and agent-initiated commands execute inside WSL2.

Opening WSL2 Folders

From PowerShell or the Windows command line:

# Open a specific Linux folder
kiro --folder-uri "vscode-remote://wsl+Ubuntu/home/username/projects"

# Open with the --remote flag
kiro --remote wsl+Ubuntu

From inside a WSL2 terminal:

# If the kiro CLI is on PATH (installed by the Windows Kiro installer)
kiro .

Note: launching kiro . from inside WSL2 doesn’t always auto-detect the WSL context correctly. If Kiro opens in Windows mode instead of WSL mode, use the explicit --folder-uri or --remote flags from PowerShell, or use the command palette (WSL: Open Folder in WSL...) from within Kiro.

A community-contributed launcher script addresses this by detecting whether the path is a WSL path and automatically constructing the correct --folder-uri:

#!/bin/bash
# Save as /usr/local/bin/kiro-wsl or replace the Kiro bin/kiro script
KIRO_ROOT="$(dirname "$(dirname "$(readlink -f "$0")")")"

ARGS=()
for arg in "$@"; do
    if [[ "$arg" != -* ]] && { [ -d "$arg" ] || [[ "$arg" == "." ]] || [[ "$arg" == ".." ]]; }; then
        FOLDER="$(realpath -m "$arg")"
        ARGS+=("--folder-uri" "vscode-remote://wsl+${WSL_DISTRO_NAME}${FOLDER}")
    elif [[ "$arg" != -* ]] && [ -f "$arg" ]; then
        FILE="$(realpath -m "$arg")"
        ARGS+=("--file-uri" "vscode-remote://wsl+${WSL_DISTRO_NAME}${FILE}")
    else
        ARGS+=("$arg")
    fi
done

"$KIRO_ROOT/Kiro.exe" "${ARGS[@]}" </dev/null &>/dev/null &
disown

The Kiro Update Breakage Cycle

This is the most significant operational issue. When Kiro updates, the kiro-server binary installed inside WSL2 (at ~/.kiro-server/) becomes incompatible with the new Kiro version. The extension tries to install a new server, and the installation script can fail — sometimes due to stale cached binaries, sometimes due to quoting bugs in the generated bash script.

The symptom is always the same:

[Error] Error resolving authority
Error: Couldn't install vscode server on remote server,
       install script returned non-zero exit status

Recovery Procedure

When WSL2 connectivity breaks after a Kiro update:

# Inside WSL2
rm -rf ~/.kiro-server

Then restart Kiro and reconnect to WSL2. The extension will perform a fresh server installation. This has been the reliable fix across multiple Kiro versions (confirmed working through v0.1.25 and beyond in the tracking issue).

The Server Installation Script Quoting Bug

In some Kiro versions, the server installation script that the extension generates contains improperly escaped single quotes ('\'') that fail in bash. If the rm -rf ~/.kiro-server approach doesn’t resolve the issue:

1. Open Kiro’s Output panel and select the WSL extension output channel
2. Copy the full bash script content from the output
3. Save it to a file inside WSL2 (e.g., ~/kiro-server-install.sh)
4. Fix the three quoting errors (look for '\'' patterns that break bash parsing)
5. Run the fixed script manually: bash ~/kiro-server-install.sh

This is a known issue in the community extension’s server bootstrapping code. The manual fix is tedious but reliable.

WSL2 Path Escaping Issues

Kiro’s agent sometimes generates Windows-style UNC paths when it should be using Linux paths inside WSL2. Commands like:

cd "\\wsl.localhost\Ubuntu\home\username\project"

…fail because the agent is constructing a Windows UNC path instead of the native Linux path /home/username/project. This is a known limitation of how the remote extension bridges the two filesystems. The agent doesn’t always correctly detect that it’s operating in a Linux context.

There’s no configuration fix for this — it’s a behavioral issue in how Kiro’s agent interacts with the remote extension’s filesystem abstraction. When it happens, the workaround is to manually correct the path in the terminal or re-prompt the agent with explicit Linux path context.

Chat Window Disabled: “Unsafe Environment”

Some users report that after connecting to WSL2, the Kiro chat sidebar shows “Drag a view here to display” or displays an “unsafe environment” warning that disables the chat window entirely. This appears to be related to workspace trust settings.

If you encounter this:

1. Open the command palette and run Workspaces: Manage Workspace Trust
2. Trust the WSL2 workspace folder
3. If the chat window still doesn’t appear, close the WSL2 window and reopen it via WSL: New Window

The alternative approach — running the Linux version of Kiro natively inside WSL2 via WSLg — avoids this issue entirely but introduces its own problems (GUI scaling issues on multi-monitor setups, occasional terminal hangs, and general WSLg instability).

MCP Servers in WSL2

This is where WSL2 support becomes particularly relevant for Kiro’s agentic workflows. MCP servers that depend on Linux toolchains — Python uvx packages, Node.js tools, Docker containers — run natively inside WSL2 rather than through Windows compatibility layers.

When Kiro connects to WSL2 via the Open Remote extension, the kiro-agent’s MCP server processes spawn inside the Linux environment. This means:

• uvx-based MCP servers use the Linux Python installation
• Docker-based MCP servers connect to the WSL2 Docker daemon
• File paths in MCP server configs use Linux paths (/home/...), not Windows paths
• Environment variables resolve from the Linux shell, not PowerShell

WSL2-Side Configuration

The ~/.kiro directory inside WSL2 is independent from %USERPROFILE%\.kiro on the Windows side. When connected to WSL2, Kiro reads:

/home/username/.kiro/
├── settings/mcp.json    # MCP servers configured for Linux execution
├── powers/              # Powers available in Linux context
├── hooks/               # Hooks that run in Linux shell
├── steering/            # Steering rules
└── secrets/             # Linux-side credentials

This natural separation means your Windows-side Kiro configuration (with Windows-native MCP servers) and your WSL2-side configuration (with Linux-native MCP servers) are already isolated by the filesystem boundary. You don’t need the persona isolation techniques to separate Windows and Linux configs — the remote extension handles that by virtue of running in a different filesystem.

The Alternative: Running Kiro Natively in WSL2

Several users in the tracking issue have tried running the Linux .deb version of Kiro directly inside WSL2 using WSLg (Windows Subsystem for Linux GUI). This bypasses the remote extension entirely — Kiro runs as a native Linux application with direct filesystem access.

It works, with caveats:

• Multi-monitor scaling: WSLg doesn’t respect Windows display scaling. On multi-monitor setups (especially mixed DPI), the mouse cursor may be oversized and click targets may be offset.
• Terminal stability: The integrated terminal can hang after extended use in some configurations.
• GTK dependencies: Requires up-to-date GTK packages in the WSL2 distribution. Missing or outdated libraries cause rendering issues.
• Performance: Noticeably slower than the remote extension approach for UI rendering.

Kiro itself discourages this approach — the Linux installer displays a message suggesting you use the Windows version with the remote extension instead. But for developers who find the remote extension’s breakage cycle unacceptable, it’s a viable if rough alternative.

Relationship to Persona Isolation

If you’re running parallel Kiro personas on Windows, WSL2 adds a third dimension to the isolation story. The Windows-side personas (director and developer) each have their own %USERPROFILE%\.kiro-* directories. When either persona connects to WSL2, it sees the single /home/username/.kiro/ inside Linux.

For most workflows this is fine — the WSL2 config is developer-focused by nature. The more common pattern is: director persona runs on Windows (Atlassian, GitLab, observability MCPs), developer persona connects to WSL2 (code toolchains, Docker, Linux-native MCP servers).

Setup Checklist

1. Install WSL2 with your preferred distribution (wsl --install -d Ubuntu)
2. Install the Open Remote - WSL extension in Kiro (jeanp413.open-remote-wsl)
3. Enable proposed API in ~/.kiro/argv.json — this is the step most people miss
4. Restart Kiro
5. Set WSL as the default terminal profile in Kiro settings
6. Open a WSL2 folder (command palette → WSL: New Window)
7. On first connection, allow the kiro-server installation inside WSL2
8. Configure ~/.kiro/settings/mcp.json inside WSL2 for Linux-native MCP servers
9. Verify MCP servers start correctly from the Kiro terminal (should show Linux paths)

After Every Kiro Update

1. If WSL2 connectivity breaks: rm -rf ~/.kiro-server inside WSL2, then restart Kiro
2. If that doesn’t work: extract the server install script from Kiro’s Output panel, fix quoting, run manually
3. Verify argv.json still contains the enable-proposed-api entry (updates occasionally reset it)

The State of Things

WSL2 support in Kiro is functional but fragile. The community extension works, the configuration is straightforward once you know about argv.json, and the recovery procedure after updates is reliable. But it’s a community-maintained bridge over a gap that arguably shouldn’t exist in a product targeting Windows developers.

The tracking issue remains open with the pending-maintainer-response label. Multiple users have requested either native WSL support or at minimum official documentation for the community extension setup. Until one of those happens, this article and that issue thread are the primary references.

References

• Kiro GitHub Issue #17: WSL Support — The canonical community thread
• Open Remote - WSL on Open VSX
• jeanp413/open-remote-wsl on GitHub
• WSL2 Documentation
• Kiro IDE: Running Parallel Personas — Companion article on persona isolation

Migration context: On May 1, 2026, AWS published the Amazon Q Developer end-of-support announcement. If you’re evaluating Kiro as the migration path from Amazon Q Developer, the timeline is now official. The configuration depth covered here is worth understanding before you commit to the switch.

My use case: a Senior Director persona loaded with Atlassian (Jira, Confluence), GitLab, NewRelic, Wiz, and AWS pricing MCPs for ticket management, architecture reviews, and operational oversight — running alongside a developer persona stripped down to Terraform, AWS docs, and code-focused tooling. These configurations don’t overlap well. The director’s MCP servers add latency, consume resources, and clutter the tool list when I’m writing code. The developer’s minimal setup lacks the integrations I need when triaging incidents or managing a sprint.

VS Code solved this years ago with profiles. Kiro inherited the --profile flag, but it doesn’t do what you’d expect.

The Problem: What --profile Actually Isolates

Kiro has two separate configuration stores:

The --profile flag creates named profiles under the VS Code state directory — separate editor settings, extensions, keybindings, and UI state. That’s the inherited VS Code profile system working as designed.

But everything that makes Kiro Kiro lives in ~/.kiro/:

~/.kiro/
├── agents/          # Agent persona definitions
├── hooks/           # Automation hooks (AWS guard rails, VPN checks)
├── powers/          # MCP power integrations (Atlassian, GitLab, etc.)
├── settings/
│   └── mcp.json     # MCP server configurations
├── steering/        # Steering rules
├── skills/          # Custom skills
└── secrets/         # Encrypted credentials

All profiles share this single ~/.kiro/ directory. There’s no flag, environment variable, or configuration option to redirect it.

How Kiro Resolves the ~/.kiro Path

I traced the path resolution through Kiro’s source to understand the full chain. There are two independent code paths that both land on ~/.kiro:

Main Process (Electron Layer)

The main Electron process resolves user data through a priority chain:

1. VSCODE_PORTABLE env var  → join(PORTABLE, "user-data")
2. VSCODE_APPDATA env var   → join(VSCODE_APPDATA, nameShort)
3. --user-data-dir flag     → direct path
4. Platform default         → macOS: ~/Library/Application Support/Kiro
                              Windows: %APPDATA%\Kiro

For ~/.kiro specifically (argv.json, extensions, policy), it uses:

// product.json: dataFolderName = ".kiro"
get argvResource() {
    const portable = process.env.VSCODE_PORTABLE;
    return portable
        ? URI.file(join(portable, "argv.json"))
        : joinPath(this.userHome, this.product.dataFolderName, "argv.json");
}

this.userHome comes from os.homedir(), which on both macOS and Windows reads the HOME / USERPROFILE environment variable.

Kiro Agent Extension (Powers, Hooks, Agents)

The kiro-agent extension — the code that actually loads powers, hooks, agents, and steering — has its own getHomeDir function:

var getHomeDir = () => {
    const { HOME, USERPROFILE, HOMEPATH, HOMEDRIVE = `C:${path.sep}` } = process.env;
    if (HOME) return HOME;
    if (USERPROFILE) return USERPROFILE;
    if (HOMEPATH) return `${HOMEDRIVE}${HOMEPATH}`;
    // ... fallback to os.homedir()
};

Then it hardcodes the .kiro string:

const powersPath = path.join(this.homeDir, ".kiro", "powers", "installed", name);
const mcpSettingsPath = path.join(this.homeDir, ".kiro", "settings", "mcp.json");
const steeringDir = path.join(this.homeDir, ".kiro", "steering");

The string ".kiro" is not read from product.json — it’s a literal in the extension bundle. This is the key constraint that shapes every solution.

What Doesn’t Work

Before covering what does work, here’s what I evaluated and rejected:

--profile flag: Only isolates VS Code state, not ~/.kiro/. Useless for this problem.

VSCODE_PORTABLE env var: Redirects the VS Code data path chain (user-data, extensions, argv), but the kiro-agent extension ignores it entirely and still reads ~/.kiro/ from HOME/USERPROFILE. Partial solution at best.

--user-data-dir flag: Same limitation — redirects VS Code state but not the kiro-agent’s ~/.kiro/ resolution.

Symlink swapping: Works for sequential use but not parallel. Two simultaneous Kiro instances would race on the symlink target.

Approach 1: HOME/USERPROFILE Override

The kiro-agent checks HOME (macOS/Linux) or USERPROFILE (Windows) before falling back to os.homedir(). Override it per instance, and each Kiro resolves a different ~/.kiro.

macOS

Create a fake home directory per persona that symlinks everything back to the real home except .kiro:

# One-time setup
REAL_HOME="$HOME"
PERSONA_HOME="$HOME/kiro-homes/engineer"
mkdir -p "$PERSONA_HOME"

# Symlink .kiro to persona-specific config
cp -R ~/.kiro ~/.kiro-engineer
ln -sfn ~/.kiro-engineer "$PERSONA_HOME/.kiro"

# Symlink everything else Kiro or shells might need
for item in .zshrc .zshenv .ssh .gnupg .gitconfig .config Library; do
    ln -sfn "$REAL_HOME/$item" "$PERSONA_HOME/$item" 2>/dev/null
done

# Launch
env HOME="$PERSONA_HOME" \
    kiro --user-data-dir "$REAL_HOME/Library/Application Support/Kiro-Engineer"

Windows (PowerShell)

$realProfile = $env:USERPROFILE
$personaHome = "$realProfile\kiro-homes\engineer"
New-Item -ItemType Directory -Force -Path $personaHome

# Copy .kiro config
Copy-Item -Recurse "$realProfile\.kiro" "$realProfile\.kiro-engineer"

# Symlink .kiro in fake home (requires Developer Mode or admin)
New-Item -ItemType SymbolicLink -Path "$personaHome\.kiro" -Target "$realProfile\.kiro-engineer"

# Symlink essentials back to real profile
foreach ($item in @('.ssh', '.gitconfig', 'AppData', 'Documents', 'Downloads')) {
    if (Test-Path "$realProfile\$item") {
        New-Item -ItemType SymbolicLink -Path "$personaHome\$item" -Target "$realProfile\$item" -ErrorAction SilentlyContinue
    }
}

# Launch
$env:USERPROFILE = $personaHome
& "$env:LOCALAPPDATA\Programs\Kiro\Kiro.exe" --user-data-dir "$realProfile\AppData\Roaming\Kiro-Engineer"
$env:USERPROFILE = $realProfile

Trade-offs: Works on both platforms. The fake home directory is the main annoyance — any tool that resolves paths relative to HOME/USERPROFILE sees the fake home. The symlinks cover common cases, but you’ll occasionally discover something missing and need to add another symlink. On Windows, creating symlinks requires either Developer Mode enabled or an elevated prompt.

Approach 2: Duplicate App with Patched product.json

Copy the Kiro installation, modify product.json to change the dataFolderName, and patch the kiro-agent extension to match. Each copy is a fully independent Kiro instance.

macOS

# Copy the app bundle
cp -R /Applications/Kiro.app /Applications/Kiro-Engineer.app

# Patch product.json
python3 -c "
import json
p = '/Applications/Kiro-Engineer.app/Contents/Resources/app/product.json'
with open(p) as f: d = json.load(f)
d['dataFolderName'] = '.kiro-engineer'
d['darwinBundleIdentifier'] = 'dev.kiro.desktop.engineer'
with open(p, 'w') as f: json.dump(d, f, indent=2)
"

# Patch the kiro-agent extension (hardcoded ".kiro" string)
sed -i '' 's/".kiro"/".kiro-engineer"/g' \
    /Applications/Kiro-Engineer.app/Contents/Resources/app/extensions/kiro.kiro-agent/dist/extension.js

# Re-sign (macOS requires valid signature)
codesign --remove-signature /Applications/Kiro-Engineer.app
codesign --force --deep --sign - /Applications/Kiro-Engineer.app

# Create the engineer's config directory
cp -R ~/.kiro ~/.kiro-engineer

The darwinBundleIdentifier change is critical — macOS uses it to distinguish app instances. With different bundle IDs, both apps appear separately in the Dock and can run truly in parallel.

Windows

No code signing needed. The parallel-instance constraint on Windows is a named mutex:

# Copy the installation
$source = "$env:LOCALAPPDATA\Programs\Kiro"
$dest = "$env:LOCALAPPDATA\Programs\Kiro-Engineer"
Copy-Item -Recurse -Path $source -Destination $dest

# Patch product.json
$productJson = "$dest\resources\app\product.json"
$product = Get-Content $productJson | ConvertFrom-Json
$product.dataFolderName = ".kiro-engineer"
$product.win32MutexName = "kiro-engineer"
$product.win32AppUserModelId = "Kiro-Engineer"
$product | ConvertTo-Json -Depth 10 | Set-Content $productJson

# Patch kiro-agent extension
$extJs = "$dest\resources\app\extensions\kiro.kiro-agent\dist\extension.js"
(Get-Content $extJs -Raw) -replace '".kiro"', '".kiro-engineer"' | Set-Content $extJs

# Create the engineer's config directory
Copy-Item -Recurse "$env:USERPROFILE\.kiro" "$env:USERPROFILE\.kiro-engineer"

# Optional: create Start Menu shortcut
$shell = New-Object -ComObject WScript.Shell
$shortcut = $shell.CreateShortcut("$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Kiro Engineer.lnk")
$shortcut.TargetPath = "$dest\Kiro.exe"
$shortcut.Save()

The win32MutexName change is the Windows equivalent of darwinBundleIdentifier — without it, the second instance would detect the mutex and hand off to the first instance instead of launching independently.

Trade-offs: Cleanest runtime behavior — no fake home directories, no symlink gymnastics, both instances use your real home directory for git, SSH, and everything else. The cost is maintenance: you re-apply the patch after every Kiro update. A 10-line script handles it.

Approach 3: Portable Mode (Partial Solution)

Kiro inherits VS Code’s portable mode. If a specific directory exists, Kiro auto-sets VSCODE_PORTABLE and redirects all VS Code state into it:

# macOS: enable portable mode
mkdir -p "/Applications/Kiro.app/Contents/Resources/kiro-portable-data/tmp"

# Windows (PowerShell): enable portable mode
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\Programs\Kiro\data\tmp"

This redirects user-data, extensions, argv.json, and policy — but not the kiro-agent’s ~/.kiro/ resolution. Powers, hooks, agents, and steering still come from the home directory. Portable mode is useful for carrying a self-contained Kiro on a USB drive, but it doesn’t solve the persona isolation problem on its own.

Recommended Setup

For parallel personas, I recommend Approach 2 (duplicate app + patch) because:

• Both instances run simultaneously with full isolation
• No fake home directories or symlink maintenance
• Each instance appears as a separate app in the Dock / Taskbar
• Git, SSH, and shell tools work normally from both instances
• The only maintenance is re-running the patch script after Kiro updates

Post-Setup: Stripping the Developer Persona

After creating ~/.kiro-engineer, remove the director-specific integrations:

# Remove director powers
rm -rf ~/.kiro-engineer/powers/atlassian
rm -rf ~/.kiro-engineer/powers/gitlab
rm -rf ~/.kiro-engineer/powers/github

# Remove director agents
rm ~/.kiro-engineer/agents/app-expert-*.md
rm ~/.kiro-engineer/agents/iac-expert-*.md

# Remove director hooks
rm ~/.kiro-engineer/hooks/aws-*.kiro.hook
rm ~/.kiro-engineer/hooks/vpn-check-gitlab.kiro.hook

Then edit ~/.kiro-engineer/settings/mcp.json to keep only coding-relevant MCP servers (Terraform, AWS docs) and remove Atlassian, GitLab, NewRelic, and Wiz.

Update Automation

macOS (update-kiro-engineer.sh)

#!/bin/bash
set -euo pipefail

APP="/Applications/Kiro-Engineer.app"
SRC="/Applications/Kiro.app"
PRODUCT="$APP/Contents/Resources/app/product.json"
EXTENSION="$APP/Contents/Resources/app/extensions/kiro.kiro-agent/dist/extension.js"

echo "Updating Kiro-Engineer from Kiro..."
rm -rf "$APP"
cp -R "$SRC" "$APP"

python3 -c "
import json
with open('$PRODUCT') as f: d = json.load(f)
d['dataFolderName'] = '.kiro-engineer'
d['darwinBundleIdentifier'] = 'dev.kiro.desktop.engineer'
with open('$PRODUCT', 'w') as f: json.dump(d, f, indent=2)
"

sed -i '' 's/\".kiro\"/\".kiro-engineer\"/g' "$EXTENSION"

codesign --remove-signature "$APP"
codesign --force --deep --sign - "$APP"

echo "Done. ~/.kiro-engineer/ config is preserved."

Windows (Update-KiroEngineer.ps1)

$source = "$env:LOCALAPPDATA\Programs\Kiro"
$dest = "$env:LOCALAPPDATA\Programs\Kiro-Engineer"

Write-Host "Updating Kiro-Engineer from Kiro..."
Remove-Item -Recurse -Force $dest -ErrorAction SilentlyContinue
Copy-Item -Recurse -Path $source -Destination $dest

$productJson = "$dest\resources\app\product.json"
$product = Get-Content $productJson | ConvertFrom-Json
$product.dataFolderName = ".kiro-engineer"
$product.win32MutexName = "kiro-engineer"
$product.win32AppUserModelId = "Kiro-Engineer"
$product | ConvertTo-Json -Depth 10 | Set-Content $productJson

$extJs = "$dest\resources\app\extensions\kiro.kiro-agent\dist\extension.js"
(Get-Content $extJs -Raw) -replace '".kiro"', '".kiro-engineer"' | Set-Content $extJs

Write-Host "Done. $env:USERPROFILE\.kiro-engineer\ config is preserved."

Platform-Specific Notes

macOS

• Ad-hoc code signing (codesign --force --deep --sign -) is required after modifying any file inside the .app bundle. macOS Gatekeeper will block unsigned modified apps.
• The darwinBundleIdentifier must differ between copies for macOS to treat them as separate applications. Without this, the second instance may not launch or may share window state with the first.
• Kiro auto-updates only affect the original /Applications/Kiro.app. The engineer copy must be manually updated via the script above.

Windows 11 Pro

• No code signing is required for locally installed applications.
• The win32MutexName must differ between copies. Windows uses a named kernel mutex for single-instance enforcement — identical mutex names cause the second launch to hand off to the existing instance.
• If Kiro was installed via the system installer (to C:\Program Files\Kiro\), copying and patching requires administrator privileges. The user installer (%LOCALAPPDATA%\Programs\Kiro\) does not have this limitation.
• Creating symbolic links on Windows requires either Developer Mode enabled in Settings or an elevated PowerShell prompt. This only matters for Approach 1 (HOME override). Approach 2 doesn’t need symlinks.
• Kiro auto-updates only affect the original installation. The engineer copy must be manually updated.

What Kiro Could Do Natively

The underlying issue is that the kiro-agent extension hardcodes ".kiro" as a string literal rather than reading dataFolderName from product.json or exposing a configuration option. If the agent resolved its config directory through the same dataFolderName mechanism the main process uses, the --profile flag or --user-data-dir could potentially isolate everything.

Even simpler: a KIRO_HOME environment variable that overrides the ~/.kiro path would eliminate the need for any of these workarounds. VS Code’s VSCODE_PORTABLE demonstrates the pattern — Kiro just needs to extend it to the agent layer.

Until then, the duplicate-and-patch approach works reliably on both platforms. The friction is real, but the workaround is a one-time setup plus a 10-second script after updates.

I discovered this when a blog post about reading time calculation crashed my build. The error pointed to a draft file, but the code it complained about was inside a Markdown code fence — supposedly safe, display-only text. It wasn’t.

Jekyll’s Liquid template engine processes every {{ }} and {% %} tag in your Markdown files before the Markdown processor ever sees them. Code fences, backtick spans, indented code blocks — none of them protect Liquid syntax from execution. If you write posts about Jekyll, Liquid, GitHub Actions, or anything else that uses double-curly-brace syntax, your examples are being silently eaten or actively breaking your build.

The Problem

Consider a blog post explaining how Jekyll’s reading time calculation works. You’d naturally include the implementation:

```liquid
{%- assign words_per_minute = 200 -%}
{%- assign number_of_words = include.post.content | number_of_words -%}
```

This looks safe. It’s inside a fenced code block. Every other language treats code fences as literal text.

Jekyll doesn’t. The Liquid engine runs first, sees the {% %} tags, and tries to execute them. In this case, include.post.content is nil (there’s no include context), so number_of_words gets nil input and the build crashes:

Liquid Exception: undefined method `split' for nil:NilClass

Why It Sneaks Up on You

The insidious part is that most unprotected Liquid doesn’t crash — it silently renders as empty text. A code example like:

```html
<meta property="og:url" content="{{ site.url }}{{ page.url }}">
```

Won’t crash because site.url and page.url are valid variables. Jekyll evaluates them, substitutes the values, and your “code example” now shows your actual URL instead of the template syntax. The Markdown renders, the page looks fine at a glance, and you don’t notice that your readers see https://mcgarrah.org/some-post/ where they should see {{ site.url }}{{ page.url }}.

You only discover the problem when:

1. A variable is nil — build crashes with undefined method errors
2. A tag is unbalanced — Liquid syntax error: 'if' tag was never closed
3. A reader reports that your code examples are blank or show wrong values
4. You view source and notice the Liquid output instead of Liquid syntax

What Triggers Build Failures vs Silent Corruption

The Fix: raw / endraw Tags

The {% raw %} and {% endraw %} tags tell Liquid to pass content through without processing. Wrap your code examples:

```liquid
{%- assign words_per_minute = 200 -%}
{%- assign number_of_words = include.post.content | number_of_words -%}
```

Place {% raw %} immediately after the opening code fence and {% endraw %} just before the closing fence.

Inline Code Too

Backtick inline code is equally unprotected. This in your Markdown:

The `{% seo %}` tag generates meta tags.

Needs to become:

The {% raw %}`{% seo %}`{% endraw %} tag generates meta tags.

The Nested raw/endraw Problem

You can’t show literal {% raw %} or {% endraw %} text inside a {% raw %} block — Liquid sees the inner {% endraw %} and terminates the block early. For posts that need to display the raw/endraw tags themselves (like this one), use HTML character entities:

<code>{&#37; raw %}</code> and <code>{&#37; endraw %}</code>

The % entity renders as %, producing {% raw %} visually while avoiding Liquid parsing.

GitHub Actions Expressions

GitHub Actions uses ${{ }} syntax which Liquid also intercepts. Any workflow YAML in a code block needs the same treatment:

```yaml
{% raw %}
- name: Build
  run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
{% endraw %}
```

Finding Every Affected File

After discovering this problem in one draft, I found it in a dozen more files. Here’s a script that scans your entire site for unprotected Liquid tags outside of raw blocks:

#!/usr/bin/env python3
"""Scan Jekyll posts/drafts for unprotected Liquid tags."""
import re, glob

LEGIT_TAGS = [
    '{% highlight', '{% endhighlight',
    '{% include', '{% post_url',
    '{% comment', '{% endcomment',
]

for f in sorted(glob.glob('_posts/*.md') + glob.glob('_drafts/*.md')):
    content = open(f).read()
    # Strip raw blocks
    cleaned = re.sub(
        r'\{%-?\s*raw\s*-?%\}.*?\{%-?\s*endraw\s*-?%\}',
        '', content, flags=re.DOTALL
    )
    # Strip front matter
    cleaned = re.sub(r'^---.*?---', '', cleaned, count=1, flags=re.DOTALL)

    found = []
    for i, line in enumerate(cleaned.split('\n'), 1):
        if '{%' in line or '{{' in line:
            s = line.strip()
            if any(x in s for x in LEGIT_TAGS):
                continue
            found.append(f'  L{i}: {s[:120]}')

    if found:
        print(f'\n=== {f} ===')
        print('\n'.join(found))

Run it from your Jekyll project root:

python3 find-unprotected-liquid.py

The script strips raw/endraw blocks and front matter first, then reports any remaining Liquid syntax. It skips legitimate Jekyll tags like {% highlight %} and {% include %} that are meant to execute.

Why This Happens

Jekyll’s rendering pipeline processes files in this order:

1. Liquid template engine — evaluates all {{ }} and {% %} tags
2. Markdown processor (Kramdown) — converts Markdown to HTML
3. Layout rendering — wraps content in layout templates

Here’s the pipeline visualized — notice that Liquid runs before Markdown has any chance to identify code fences:

flowchart TD
    A["📄 Markdown Source File"] --> B["1️⃣ Liquid Template Engine"]
    B --> |"Evaluates ALL &#123;&#123; &#125;&#125; and &#123;% %&#125; tags"| C{"Tag inside<br/>raw/endraw?"}
    C --> |Yes| D["Pass through as literal text"]
    C --> |No| E{"Valid variable<br/>or tag?"}
    E --> |"Yes — e.g. site.url"| F["🔇 Silent substitution<br/>renders actual value"]
    E --> |"No — e.g. nil variable"| G["💥 Build crash<br/>undefined method error"]
    E --> |"Unbalanced tag"| H["💥 Build crash<br/>Liquid syntax error"]
    D --> I["2️⃣ Kramdown Markdown Processor"]
    F --> I
    I --> |"NOW identifies code fences<br/>but Liquid already ran"| J["HTML Output"]
    J --> K["3️⃣ Layout Rendering"]
    K --> L["📄 Final Page"]

    style B fill:#e74c3c,color:#fff
    style I fill:#3498db,color:#fff
    style K fill:#2ecc71,color:#fff
    style F fill:#f39c12,color:#fff
    style G fill:#c0392b,color:#fff
    style H fill:#c0392b,color:#fff
    style D fill:#27ae60,color:#fff

The key insight: Liquid has no concept of Markdown code fences. By the time Kramdown identifies your triple-backtick block, Liquid has already consumed or evaluated everything inside it.

This is documented in Jekyll’s Liquid processing docs, but it’s easy to miss because every other context where you write code (GitHub READMEs, Stack Overflow, documentation sites) treats code fences as sacred.

Posts That Commonly Need This

If you write about any of these topics, check your code examples:

• Jekyll configuration — {{ site.* }}, {{ page.* }} variables
• Liquid templates — {% if %}, {% for %}, {% assign %} tags
• GitHub Actions workflows — ${{ secrets.* }}, ${{ env.* }}, ${{ steps.* }}
• Jinja2 templates — same {{ }} syntax as Liquid
• Ansible playbooks — {{ variable }} syntax
• Mustache/Handlebars — {{ }} and {{{ }}} syntax
• Vue.js templates — {{ }} interpolation syntax

Lessons Learned

1. Code fences are not a security boundary for Liquid. Never assume content inside backticks is safe from template processing.
2. Silent failures are worse than crashes. The posts that render “successfully” with wrong content are harder to catch than the ones that blow up the build.
3. Scan proactively. After fixing one post, scan everything. The same pattern tends to appear in clusters — if you wrote one post about Jekyll internals, you probably wrote several.
4. Keep the detection script. Run it as part of your pre-commit or CI workflow to catch new instances before they ship.

Related Posts

• How the Sausage Is Made: Every Feature Powering This Jekyll Blog — Complete feature reference including Liquid escaping
• Mermaid Diagram Rendering Challenges — Another case where Jekyll’s rendering pipeline causes surprises

References

• Jekyll Liquid Processing — Official docs on how Liquid interacts with content
• Liquid raw Tag — Shopify’s Liquid documentation
• Jekyll Rendering Order — The pipeline that explains why Liquid runs before Markdown

I run a multi-monitor setup on my macOS workstation and this drove me crazy until I tracked down the actual causes and fixes. None of this is complicated, but Apple does not make it obvious.

Why the Dock Jumps

The Dock follows a simple rule: it appears on whichever display the cursor pushes against the bottom edge. If your cursor drifts to the bottom of a secondary monitor — even briefly — macOS moves the Dock there. This is by design, not a bug. Apple considers it a feature for multi-monitor workflows.

Three things make it worse:

• Accidental activation — The Dock jumps when the cursor hits the bottom of an inactive display. If you are moving the mouse quickly between screens, you will trigger this constantly.
• External display wakeup — When macOS wakes from sleep, it can default the Dock to the wrong display. This is especially common with external monitors that take a moment to handshake.
• Display arrangement — If your displays are arranged vertically in System Settings → Displays → Arrangement, the Dock behaves unpredictably because the bottom edge of one display overlaps with the top of another.

The Quick Fix: Click and Hold

The fastest way to move the Dock back is also the least documented:

1. Move your cursor to the very bottom edge of the screen where you want the Dock.
2. Push the cursor down against the edge and hold it there for 2–3 seconds.
3. The Dock slides back to that display.

This is not a permanent fix — the Dock will jump again the next time you trigger it — but it is the fastest recovery when it happens.

The Permanent Fix: Mission Control Settings

The setting that causes most of the jumping is buried in Mission Control:

1. Open System Settings → Desktop & Dock.
2. Scroll down to the Mission Control section.
3. Toggle off “Automatically rearrange Spaces based on most recent use”.

This setting causes macOS to reorder your Spaces (and by extension, the Dock’s display assignment) based on which screen you used most recently. Turning it off keeps your Spaces — and the Dock — where you put them.

While you are in that settings panel, also check:

• “Displays have separate Spaces” should be enabled. This gives each monitor its own menu bar and improves multi-monitor behavior overall. Without it, macOS treats all displays as one continuous Space, which makes the Dock even more prone to wandering.

Note that toggling “Displays have separate Spaces” requires a logout and login to take effect.

Display Arrangement Matters

If your monitors are physically side by side but macOS thinks one is above the other, the Dock will behave strangely. Check your arrangement:

1. Open System Settings → Displays.
2. Click Arrange… (or drag the display icons directly in newer macOS versions).
3. Make sure the display positions match your physical layout.
4. The white bar at the top of one display icon indicates which monitor has the menu bar — drag it to your primary display if it is on the wrong one.

The key detail: the Dock lives on the display with the white menu bar by default, but it can still jump to other displays. The main monitor (white bar) and the Dock’s home display are independent — you can have the menu bar on your laptop screen and pin the Dock to an external monitor, or vice versa. Understanding this distinction is what makes the arrangement settings click.

Vertical arrangements are particularly problematic because the bottom edge of the top display and the top edge of the bottom display share a boundary. The Dock can get confused about which display owns the bottom edge.

The Displays settings panel is the starting point — note the Arrange… button in the lower right corner:

Clicking Arrange… opens the arrangement view where you drag displays to match your physical layout. The key detail is the instruction at the top: “To relocate the menu bar, drag it to a different display.” The menu bar — and by default the Dock — is hard-wired to whichever display has that white bar:

Vertical arrangements are particularly problematic because the bottom edge of the top display and the top edge of the bottom display share a boundary. The Dock can get confused about which display owns the bottom edge.

Summary

The Mission Control toggle is the one that fixes it for most people. If you only do one thing, do that.

Here are six features that each took less than a day to implement but collectively transformed this blog from a default Jekyll template into something that feels intentional.

Dark/Light Theme

The blog automatically matches the reader’s operating system preference — dark mode on dark systems, light mode on light systems. No toggle button, no JavaScript, no cookie to remember the choice.

Implementation

The entire dark mode is a single CSS media query in _sass/basic.sass:

@media (prefers-color-scheme: dark)
  body
    background: $dark
    color: $light

The $dark and $light variables come from the Contrast theme’s SASS variable system. The theme was designed with dark mode support from the beginning (the original author, Niklas Buschmann, added it in December 2019), but it needed maintenance as I added features.

The Mermaid Dark Mode Fix

When I added Mermaid diagram support in September 2025, the diagrams rendered with a white background in dark mode — a blinding white rectangle in an otherwise dark page. The fix was detecting the color scheme in JavaScript and passing it to Mermaid’s initialization:

const isDarkMode = window.matchMedia &&
  window.matchMedia('(prefers-color-scheme: dark)').matches;
mermaid.initialize({
  startOnLoad: true,
  theme: isDarkMode ? 'dark' : 'default'
});

The Google Custom Search widget also needed dark mode styling (_sass/google-search.sass), and the Giscus comment widget gets it for free via the preferred_color_scheme theme setting.

Why No Toggle?

Some blogs add a manual dark/light toggle button. I chose not to because:

• OS preference is the right default — If someone set their system to dark mode, they want dark mode everywhere
• No JavaScript dependency — The CSS media query works without JavaScript, in RSS readers, and in print
• No state to manage — No cookie, no localStorage, no flash of wrong theme on page load

The Contrast theme originally had a dark_theme: true/false config option for a site-wide override. I removed that in favor of the automatic approach.

Print Stylesheet

Technical blog posts get printed. People print Proxmox walkthroughs to have next to the server, or save Ceph commands as PDF references. The default Jekyll output looks terrible when printed — navigation bars, comment widgets, and copy buttons all show up on paper.

Implementation

The print stylesheet (_sass/print.sass, added September 11, 2025) is 134 lines that handle three things:

1. Hide non-content elements:

@media print
  nav, aside, footer, .giscus, .page__comments,
  .btn-copy, .gcse-search, header nav,
  .taxonomies-list, .more
    display: none !important

2. Reset to print-friendly typography:

  body
    background: white !important
    color: black !important
    font-family: "Times New Roman", serif !important
    font-size: 12pt !important
    line-height: 1.4 !important

3. Make links useful on paper:

Printed pages can’t be clicked, so links need to show their URLs. The stylesheet appends the URL after each link text so the reader can type it in.

The SASS Circular Dependency

Adding the print stylesheet triggered a SASS circular dependency nightmare — the same day I added it, I had to restructure the entire SASS architecture to eliminate circular imports. That story is told in SASS Circular Dependency Nightmare.

Custom Error Pages with Haiku

GitHub Pages serves a generic error page by default. Custom error pages are a small touch that shows the site is maintained and gives lost visitors a way back.

404: Page Not Found

---
permalink: /404.html
title: "404: Page not found"
layout: default
sitemap: false
---

<article>
  <header><h1><a href="https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found"
    target="_blank">404 Not Found</a></h1></header>
  <p>
    <i>You step in the stream,</i><br>
    <i>but the water has moved on.</i><br>
    <i>This page is not here.</i><br>
  </p>
</article>

500: Internal Server Error

<p>
  <i>Server, dark within,</i><br>
  <i>Unexpected fault appears,</i><br>
  <i>Try again, please wait.</i><br>
</p>

Design Decisions

• Haiku format — A 5-7-5 syllable poem is memorable and human. It signals that a person built this site, not a template generator
• RFC links — The error code in the heading links to the actual HTTP specification. A small nod to the technically curious reader
• sitemap: false — Error pages should never appear in the sitemap
• Uses the default layout — The error page has the same navigation as the rest of the site, so the reader can find their way back

The 404 page went through four commits between 2020 and 2024, mostly simplifying it from the original theme’s version down to the haiku format.

Author Bio

Every post ends with an author bio section — a short paragraph with credentials and links to professional profiles. This was added on April 2, 2026 as part of E-E-A-T improvements for AdSense approval.

Implementation

The bio lives in _includes/author-bio.html:

<div class="author-bio">
  <strong>About the Author:</strong>
  <a href="/about/">Michael McGarrah</a> is a Cloud Architect with 25+ years
  in enterprise infrastructure, machine learning, and system administration.
  He holds an M.S. in Computer Science (AI/ML) from Georgia Tech and a B.S.
  in Computer Science from NC State University, and is currently pursuing an
  Executive MBA at UNC Wilmington.
  <span class="author-links">
    <a href="https://www.linkedin.com/in/michaelmcgarrah/" rel="me">LinkedIn</a> ·
    <a href="https://github.com/mcgarrah" rel="me">GitHub</a> ·
    <a href="https://orcid.org/0000-0001-8935-1293" rel="me">ORCID</a> ·
    <a href="https://scholar.google.com/citations?user=Lt7T2SwAAAAJ" rel="me">Google Scholar</a> ·
    <a href="/resume/">Resume</a>
  </span>
</div>

Why It Matters

• E-E-A-T signals — Google’s Experience, Expertise, Authoritativeness, and Trustworthiness framework rewards content with clear author attribution. The bio provides credentials, the rel="me" links establish identity across platforms
• Reader trust — A reader deciding whether to follow a Ceph walkthrough wants to know the author has relevant experience
• Professional visibility — Every post becomes a touchpoint to LinkedIn, GitHub, ORCID, and the resume

The bio includes dark mode support via SASS theme variables and is automatically included in every post via the post.html layout.

Archive Page

The archive page at /archive/ provides a chronological listing of every post. It’s the simplest navigation feature on the site — just titles and dates, sorted newest first.

History

The archive page has the longest history of any feature on this blog:

• January 2020 — Original archive include added to the Contrast theme by Niklas Buschmann
• August 2023 — I created archive.html as a standalone page
• December 2025 — Moved from a temporary _jmm debug directory to _layouts/archive.html (a cleanup of my own mess)

It works alongside the tag pages (/tags/), category pages (/categories/), and the paginated homepage to give readers multiple ways to find content. The archive is the “just show me everything” option.

Favicon

The blog has a basic favicon.ico file at the site root. It’s the minimum viable favicon — a single .ico file that browsers pick up automatically without any <link> tags in the HTML.

This is one of the items still on the TODO list for improvement — a proper favicon set would include multiple sizes (16x16, 32x32, 180x180 for Apple Touch), PNG format, and a site.webmanifest file. But the basic .ico works and prevents the 404 that browsers generate when they request /favicon.ico and find nothing.

Update: This has since been addressed — you will see an upcoming favicon post shortly.

The Compound Effect

None of these features would justify a blog post on their own. But together they create a compound effect:

• A reader arrives from a Substack link → the site matches their dark mode preference
• They read a Ceph walkthrough → the author bio establishes credibility
• They print the article for reference → the print stylesheet gives them clean output
• They mistype a URL → the haiku 404 page makes them smile instead of bounce
• They want to browse more → the archive page shows everything chronologically

Each feature took less than a day. The total investment was maybe a week across two years. The return is a site that feels maintained and intentional — which matters more than any individual feature.

Related Posts

• Improving E-E-A-T for Jekyll and AdSense — The author bio and credibility signals
• SASS Circular Dependency Nightmare — Triggered by adding the print stylesheet
• Jekyll Website Optimization Part 1 — Dark mode and theme improvements
• Jekyll Website Optimization Part 2 — Error pages and UX polish
• How the Sausage Is Made — Full feature inventory

If you use VS Code across macOS, Windows, and WSL2, you have probably noticed that the Markdown preview experience is not consistent across platforms.

All three platforms have the “Open Preview to the Side” button in the editor title bar — the split-pane icon in the top-right corner. That button is always there:

Here is a closer look at that button area:

The difference is in the right-click context menu. On macOS, right-clicking a Markdown file in the Explorer gives you “Open Preview” and “Open Preview to the Side” right at the top of the menu — one click and you are in the preview:

On Windows and WSL2/Linux, those options are missing from the context menu. Instead you only get “Open With…” which opens a secondary list of editors to choose from:

Clicking “Open With…” reveals a submenu where you have to pick the editor — an extra click and a hunt every time you want to preview a Markdown file:

The keyboard shortcut Ctrl+Shift+V still works on all platforms, but if you are a mouse-driven user or just want the same quick context menu experience everywhere, this gap is a daily annoyance.

This article covers how to close that gap — both with built-in settings and with Markdown Preview Enhanced as a longer-term fix.

Why Is the Context Menu Different?

VS Code treats WSL as a “Remote” environment. Extensions, settings, and default file associations do not always sync between the local host (macOS or Windows) and the remote WSL instance. The built-in Markdown Language Features extension can end up disabled or overridden in the remote context, which removes the preview options from the context menu.

The same issue appears on native Windows or Linux installs when another extension claims the .md file type or when the built-in Markdown extension is not the default handler.

Fix 1: Re-Enable the Built-In Markdown Extension

If the context menu is missing the preview options, the built-in Markdown Language Features extension is likely disabled in your current environment.

1. Open the Extensions view (Ctrl+Shift+X).
2. Search for @builtin markdown.
3. Verify that “Markdown Language Features” is enabled. If it shows as disabled for your WSL connection, click Enable (Workspace) or Enable.

Fix 2: Set the Default Editor for Markdown

Even with the extension enabled, VS Code may still show “Open With…” instead of “Open Preview” in the context menu. Setting the default editor for .md files tells VS Code to stop asking:

1. Right-click any .md file in the Explorer.
2. Select Open With…
3. At the bottom of the list, select Configure default editor for ‘*.md’.
4. Choose Markdown Preview.

Markdown Shortcut Cheat Sheet

These three shortcuts work on all platforms regardless of icon visibility:

On macOS, substitute Cmd for Ctrl.

The Better Fix: Markdown Preview Enhanced

The built-in preview is functional but minimal. Markdown Preview Enhanced (MPE) is the power-user alternative — and it fixes the context menu gap as a side effect, because it registers its own dedicated commands and context menu entries that work consistently across all platforms.

After installing MPE, you get a dedicated preview icon in the editor title bar that works reliably across all platforms:

Why MPE Is an Upgrade

• Math and diagrams: Native KaTeX/MathJax support for formulas, plus Mermaid, PlantUML, and Flowchart.js for diagrams — no extra extensions needed.
• Image path handling: Resolves local image paths in WSL more gracefully than the built-in preview, which sometimes struggles with \\wsl$ file resolution.
• Export options: Direct export to PDF, PNG, HTML, ePub, and Marp/Pandoc presentations.
• Code chunk execution: Can run code blocks in your Markdown (if the compiler is installed in your environment) and render the output inline in the preview.

Here is MPE rendering a side-by-side preview with rich content that the built-in preview cannot handle:

Auto-Open Preview

To make MPE open the preview automatically whenever you open a Markdown file:

1. Open Settings (Ctrl+,).
2. Search for markdown-preview-enhanced.previewConfig.automaticallyShowPreviewOfMarkdownBeingEdited.
3. Toggle it on.

WSL2 Performance Note

MPE uses a heavier rendering engine than the built-in preview. On very large files (10k+ lines) inside a WSL container, you may notice scroll lag. If that happens, check the Puppeteer settings in the MPE extension options to tune rendering performance.

Summary

The Markdown preview context menu gap between macOS and Windows/WSL2 is a VS Code quirk caused by remote environment extension sync and default editor associations. You can fix it by re-enabling the built-in Markdown Language Features extension and setting the default editor for .md files — or skip the workaround entirely by installing Markdown Preview Enhanced, which provides consistent context menu entries and a feature-rich preview across macOS, Windows, and WSL2.