GitHub Pages Plugin Constraints

Local Jekyll and hosted Jekyll are related environments, not automatically identical environments.

That matters most when plugins enter the build.

Two deployment approaches to understand

GitHub Pages currently supports publishing from a branch and publishing through a custom GitHub Actions workflow.

GitHub's current documentation recommends GitHub Actions when you want more control over the build/automation path.

A branch-based Pages build uses GitHub's supported Jekyll environment and constraints.

A custom workflow can give you more explicit control over dependency installation and the Jekyll build before the generated artifact is deployed.

Do not memorize a plugin whitelist forever

Supported versions/plugins change over time.

The course rule is:

Before depending on a plugin, verify it against the current official GitHub Pages/Jekyll documentation and your chosen publishing path.

The source map for this Unit records that this deployment constraint was checked against official GitHub documentation on 2026-08-10.

Compatibility evidence

For a candidate plugin, record:

Plugin:
Local build works? yes/no
Chosen Pages mode: branch / custom Actions workflow
Current official support evidence:
Production build evidence:
Fallback if unsupported:

Failure pattern

Local build:

PASS

GitHub Pages build:

FAIL: dependency/plugin unavailable or disallowed

That pattern does not mean the plugin code suddenly changed in transit.

It tells you to compare environments/build policies.

Security boundary

Do not paste arbitrary third-party plugin code into _plugins merely to bypass a hosting restriction.

You would be adding executable build code whose behavior and maintenance you now own.

Checkpoint

Explain why plugin compatibility is part of deployment architecture, not only local Jekyll configuration.