jekyll-infops-theme

Terminal — Creating Commands, Games & Interactive Programs

2025-01-10T00:00:00+01:00

The terminal embedded in the hero section is fully extensible. You can add text commands, canvas games, or any interactive program in a few minutes.

Architecture overview

assets/js/
├── modules/
│   └── hero-terminal.js        ← Terminal engine (ctx API)
└── terminal-commands/
    ├── help.js                 ← Auto-built from registry
    ├── system.js               ← clear / cls
    ├── color.js                ← color command
    ├── fun.js                  ← matrix
    ├── pong.js                 ← Canvas game
    ├── pacman.js               ← Canvas game
    ├── snake.js                ← Canvas game
    └── tetris.js               ← Canvas game

Every command file calls window.Terminal.register() and is loaded via a

That’s it. Rebuild Jekyll and type hello in the terminal.

The `ctx` API

The ctx object is passed to every command’s run function.

Method / Property	Description
`ctx.printLine(text, cssClass, delayMs)`	Print a line of text
`ctx.printLines(array, cssClass, baseDelay)`	Print multiple lines
`ctx.clearOutput()`	Clear the terminal
`ctx.hideOutput()`	Hide output + input (for games)
`ctx.showOutput()`	Restore output + input
`ctx.stopGame()`	Stop canvas loop, restore terminal
`ctx.canvas`	The element
`ctx.getGameDimensions()`	Returns `{W, H}` — usable canvas size
`ctx.resizeForGame(W, H)`	Resize terminal to fit game, returns Promise
`ctx.getAccentColor()`	Returns `{r, g, b}` — current user/theme accent
`ctx.isFullscreen()`	`true` if terminal is in fullscreen mode
`ctx.gameLoop.set(handle)`	Set rAF handle

CSS classes for `printLine`

Class	Appearance
`term-out`	Default accent color
`term-out-bold`	Bright accent, bold
`term-out-dim`	Dimmed accent
`term-out-error`	Red
`term-out-warn`	Yellow
`term-out-info`	Light blue
`term-out-ascii`	Small, dimmed — for ASCII art

Text commands

window.Terminal.register({
  name: 'uptime',
  help: ['uptime', 'Show page uptime'],
  run: function(args, ctx) {
    var s = Math.floor(performance.now() / 1000);
    ctx.printLine('up ' + Math.floor(s/60) + 'm ' + (s%60) + 's', 'term-out');
  }
});

Canvas games

Pattern: resizeForGame + getAccentColor

(function() {
  var keyH = null;
  function cleanup(ctx) {
    if (keyH) document.removeEventListener('keydown', keyH);
    keyH = null;
    ctx.stopGame();
  }

  window.Terminal.register({
    name: 'mygame',
    help: ['mygame', 'My canvas game', 'games'],
    run: function(args, ctx) {
      ctx.stopGame(); ctx.hideOutput();

      // Compute desired size from viewport
      var W = Math.min(window.innerWidth - 40, 800);
      var H = Math.min(window.innerHeight - 140, 500);

      ctx.resizeForGame(W, H).then(function() {
        var canvas = ctx.canvas; if (!canvas) return;
        var dim = ctx.getGameDimensions();
        W = dim.W; H = dim.H;
        canvas.style.display = 'block'; canvas.style.height = H + 'px';
        canvas.width = W; canvas.height = H;

        var c = canvas.getContext('2d');
        var x = W/2, y = H/2;

        keyH = function(e) {
          if (e.key === 'Escape') { cleanup(ctx); return; }
          if (e.key === 'ArrowLeft')  x -= 8;
          if (e.key === 'ArrowRight') x += 8;
          if (e.key === 'ArrowUp')    y -= 8;
          if (e.key === 'ArrowDown')  y += 8;
        };
        document.addEventListener('keydown', keyH);
        ctx.printLine('Arrow keys · ESC to quit', 'term-out-bold');

        function loop() {
          // Read accent color every frame — changes instantly with color command
          var ac = ctx.getAccentColor();
          var light = document.documentElement.getAttribute('data-theme') === 'light';

          c.fillStyle = light ? '#f0f4fc' : '#070d18';
          c.fillRect(0, 0, W, H);

          var color = 'rgba('+ac.r+','+ac.g+','+ac.b+',.9)';
          c.beginPath(); c.arc(x, y, 20, 0, Math.PI * 2);
          c.fillStyle = color; c.shadowColor = color; c.shadowBlur = 12;
          c.fill(); c.shadowBlur = 0;

          ctx.gameLoop.set(requestAnimationFrame(loop));
        }
        loop();
      });
    }
  });
})();

Adding to `/help`

The help array:

help: ['command syntax', 'Description']          // regular command
help: ['command syntax', 'Description', 'games'] // listed under Games section

Customizing the neofetch boot screen

Edit _config.yml:

theme_config:
  terminal_user: "user@infops"   # header label
  terminal_boot:
    user:  "loup"
    host:  "infops"
    os:    "AlmaLinux 10"
    shell: "bash 5.2"
    role:  "SysOps"
    line1: "Org: My Company"
    line2: "Stack: Docker · Proxmox"
    motd:  "Type /help for commands."
    ascii: |
      ██╗███╗   ██╗███████╗
      ██║████╗  ██║██╔════╝
      ██║██╔██╗ ██║█████╗
      ██║██║╚██╗██║██╔══╝
      ██║██║ ╚████║██║
      ╚═╝╚═╝  ╚═══╝╚═╝

Leave any field as "" to hide that line. Leave ascii empty to use the default Ubuntu-style logo.

FAQ & Troubleshooting

2025-01-09T10:00:00+01:00

Collected answers to everything that tends to go wrong during setup, customisation and deployment.

Build & installation

`bundle install` fails on Windows

# Force native Ruby platform (no native extensions)
bundle config set --local force_ruby_platform true
bundle install

If you get SSL errors:

gem update --system
gem install bundler
bundle install

Sass `@import` deprecation warning

This theme uses Dart Sass @use / @forward. The warning appears if your environment falls back to LibSass (sassc gem):

# Ensure jekyll-sass-converter 3.x is installed
bundle update jekyll-sass-converter
bundle exec jekyll serve

Check which converter is active: bundle info jekyll-sass-converter.

Line numbers appear inside code blocks

Set line_numbers: false in _config.yml:

kramdown:
  syntax_highlighter_opts:
    block:
      line_numbers: false

Then restart Jekyll. Existing _site/ files may be stale — run bundle exec jekyll clean first.

`"Could not locate Gemfile"` or missing include

Ensure you’re in the project root when running bundle exec jekyll serve. Double-check that all files referenced by Liquid include tags exist in _includes/.

Jekyll builds successfully but the site looks broken

Check baseurl in _config.yml — for a GitHub Pages project site it must be /repo-name, for a user/org site it must be ""
Open browser DevTools → Console for 404s on CSS/JS
Run bundle exec jekyll build --verbose for the full build log

Layout & display

Expected — at < 1100px the sidebar collapses below the content and switches to a 2-column grid. At < 768px it becomes a single column. This is by design and controlled in _sass/_responsive.scss.

Canvas background is invisible

Check canvas.enabled: true in _config.yml
DevTools → Console: look for JS errors in canvas.js
Reduce particle_count to 40 and lower max_distance to 80 to rule out performance issues
Some ad-blockers block canvas API calls — test in a private window

Hero section is too tall

# _data/theme.yml
hero:
  min_height: 40   # vh — reduce this; set to 0 for auto height

Post card left border missing

The coloured left border comes from .post-card::before in _sass/_layout.scss. If you’ve customised SCSS, verify this rule exists and isn’t overridden by a display: none or content: none somewhere.

Search bar does nothing

The search page is at /search/. Confirm:

pages/search.html has the front matter block at the very top of the file (no Liquid tags before the ---)
search.json exists at the repo root with a layout: null front matter
The search-json-url meta tag is present in (check _site/search/index.html)
Open DevTools → Network — the fetch to /search.json should return 200 with valid JSON

Terminal

Terminal color doesn’t persist across pages

The terminal color is stored in sessionStorage, not localStorage. It persists within the same tab session but resets when the tab is closed or a new tab is opened. This is intentional — it’s a visual preference for the current session, not a permanent setting.

Games feel too fast or too slow

Game speed is frame-rate dependent (60fps assumed). On very high refresh-rate monitors (144Hz+), games run faster because requestAnimationFrame fires more frequently. A fix using performance.now() delta timing could be added to each game file if needed.

Terminal doesn’t respond to keyboard input

Click inside the terminal window first — the hidden needs focus. If the terminal is minimised (yellow dot), click the dot to restore it.

Analytics

GoatCounter shows `—` for visitor count

Two causes:

Public stats disabled: GoatCounter dashboard → Settings → Allow public access to stats → Enable.

CORS blocked: Open DevTools → Network → filter goatcounter.com. A 403 means public stats are off. A CORS error means a browser extension is blocking the request. Check the console for [infops] GoatCounter stats: auth-required.

Analytics fire in development

Check that analytics.html wraps all script tags inside a if jekyll.environment == "production" Liquid condition. Run bundle exec jekyll serve (not --env production or JEKYLL_ENV=production).

GA4 shows no data for 24–48 hours

Normal — GA4 processes data asynchronously with up to 48h delay. Verify the Measurement ID starts with G- (not the old UA- Universal Analytics format).

GitHub Pages

Build fails in GitHub Actions

Check the Actions tab for the error. Common causes:

Error	Fix
`Gem not found`	Add the gem to `Gemfile` and commit `Gemfile.lock`
`Plugin not whitelisted`	The `.github/workflows/pages.yml` Action-based workflow bypasses the whitelist — ensure Source is set to GitHub Actions, not Deploy from branch
`baseurl` mismatch	Match `baseurl` in `_config.yml` to your repo name
Jekyll build error in a post	Run `bundle exec jekyll build` locally to see the exact error

Site deploys but shows old content

GitHub Actions build + deploy takes 1–3 minutes. Check Actions → latest workflow run for status. If the run succeeded but the site is still stale, try a hard refresh (Ctrl+Shift+R) — GitHub Pages serves behind a CDN with some caching.

Custom domain returns 404

Ensure a CNAME file exists at the repo root containing your domain (e.g. blog.yourdomain.com)
Add a CNAME DNS record pointing to your-username.github.io
Wait up to 24h for DNS propagation
In repo Settings → Pages → Custom domain — GitHub checks DNS and provisions a TLS certificate automatically

Docker

`docker compose up` fails on first run

# Full reset — remove containers, volumes and cached layers
docker compose down -v
docker compose build --no-cache
docker compose up

Changes not reflected after `docker compose up`

Confirm the source directory is mounted as a volume in docker-compose.yml:

volumes:
  - .:/srv/jekyll

If you edited _config.yml, livereload is not sufficient — restart the container: docker compose restart jekyll.

Analytics Setup — GoatCounter, GA4, Plausible & Umami

2025-01-08T10:00:00+01:00

jekyll-infops-theme supports four analytics providers simultaneously. All scripts are injected only when JEKYLL_ENV=production — running jekyll serve locally never fires any tracker.

How production mode works

# Development — no analytics injected
bundle exec jekyll serve

# Production build — all configured providers active
JEKYLL_ENV=production bundle exec jekyll build

# Docker production — sets JEKYLL_ENV=production automatically
docker compose -f docker-compose.prod.yml up -d --build

# GitHub Actions — pages.yml sets JEKYLL_ENV=production in the build step

The analytics.html include evaluates jekyll.environment at build time. If it’s not production, the output is an empty string — no