baseurl and url compatibility boundary between Jekyll 4.x local builds and GitHub Pages production

URL Composition and Normalization

Jekyll 4.x and the GitHub Pages runtime (currently based on Jekyll 4.2.x) normalize baseurl identically. Both environments strip any leading slash from the baseurl definition and ensure a single trailing slash during internal URL composition. For example, defining baseurl: "/project" or baseurl: "/project/" results in the same internal normalization to /project/.

Consistent Canonical URLs Across Environments

To maintain consistent link generation without maintaining multiple configuration files, define your production values in _config.yml and override the local environment via the CLI. This ensures that the logic used to generate relative paths remains identical between local and production builds.

Recommended Configuration

# _config.yml
url: "https://username.github.io"
baseurl: "/repository-name"

Local Execution Command

When running locally, use the --url flag to override the production domain while keeping the baseurl intact. This prevents divergent pathing for assets and internal links:

bundle exec jekyll serve --url "http://localhost:4000"

Plugin Availability and Silent Failures

GitHub Pages utilizes a strict whitelist of supported plugins. If a plugin listed in your _config.yml is not on this whitelist, the GitHub Pages runtime silently ignores it. The build process will not fail or throw a critical error; however, any functionality, liquid tags, or filters provided by that plugin will be absent from the production site.

To verify plugin compatibility locally, you can use the jekyll-github-pages gem, which mimics the GitHub Pages environment and whitelist constraints.

Verification Steps

• Version Check: Run jekyll -v locally to ensure you are on a 4.x release.
• Path Audit: Inspect the _site directory after a local build to confirm that baseurl is being prepended to assets as expected.
• Log Inspection: Check the GitHub Actions build logs for warnings indicating that specific plugins were ignored during the production build.

Diagnostic Note: Please clarify if this is a User/Organization site (username.github.io) or a Project site (username.github.io/repo/), as User sites typically require an empty baseurl.