Relative links in Jekyll on Github Pages and localhost are not working correctly

Question

I use Gulp to run Jekyll. My setup works fine on localhost, but when I introduce Github Pages relative links stop working. I use gulp-gh-pages npm package to push _site contents to gh-pages branch.

Contents of gulpfile.js related to Jekyll and Github Pages:

var browserSync  = require('browser-sync').create();
var gulp         = require('gulp');
var runSequence  = require('run-sequence');
var ghPages      = require('gulp-gh-pages');
var gutil        = require('gulp-util');
var run          = require('gulp-run');
var del          = require('del');

gulp.task('build:jekyll', function(callback) {
    var shellCommand = 'jekyll build --incremental';

    return gulp.src('')
        .pipe(run(shellCommand))
        .on('error', gutil.log);

    callback();
});

gulp.task('clean', function() {
    return del(['_site', 'assets']);
});

// [`build:scripts`, `build:styles`, `build:images`] is removed from the runSequence example for MVP
gulp.task('build:prod', function(callback) {
    return runSequence('clean', 'build:jekyll', callback)
    browserSync.reload();
});

gulp.task('deploy',['build:prod'], function(){
    return gulp.src('./_site/**/*')
        .pipe(ghPages());
});

Contents of config.yml :

baseurl: /

collections:
  pages:
    output: true
    permalink: /:title/

exclude: ["_assets", "gulpfile.js", "node_modules", "package.json", "package-lock.json", ".jekyll-metadata"]

Reference to assets:

<link rel="stylesheet" href="{{ site.baseurl }}assets/styles/main.min.css">

Front matter on every page inside _pages directory:

---
layout: page
title: Title
description: Awesome description
image: https://source.unsplash.com/random/?water
---

Here is the link to my Github repository with full source code: https://github.com/alljamin/portfolio

How can I configure Gulp and Jekyll so all the relative links work both locally and on Github Pages?

Answer 1

Try : " baseurl: /portfolio "

Generate url with {{site.baseurl}}/path/to/res or {{ "/path/to/res" | prepend: site.baseurl }} {{ "/path/to/res" | prepend: site.baseurl }} .

Answer 2

Elaborating on the @david-jacquel answer I was able to find a way to successfully run localhost and Github Pages environments via separate Gulp tasks.

Contents of gulpfile.js :

gulp.task('build:jekyll:dev', function(callback) {
    var shellCommand = 'jekyll build --incremental --baseurl "" ';

    return gulp.src('')
        .pipe(run(shellCommand))
        .on('error', gutil.log);

    callback();
});

gulp.task('build:jekyll:prod', function(callback) {
    var shellCommand = 'jekyll build --incremental';

    return gulp.src('')
        .pipe(run(shellCommand))
        .on('error', gutil.log);

    callback();
});

The build:jekyll:dev task will overwrite the _config.yml baseurl to "" . So I can do something like this:

gulp.task('build:dev', function(callback) {
    return runSequence('clean', ['build:scripts', 'build:styles', 'build:images'], 'build:jekyll:dev', callback)
    browserSync.reload();
});

gulp.task('build:prod', function(callback) {
    return runSequence('clean', ['build:scripts', 'build:styles', 'build:images'], 'build:jekyll:prod', callback)
    browserSync.reload();
});

gulp.task('serve', ['build:dev'], function() {
    browserSync.init({
        server: {
            baseDir: "_site"
        },
        ghostMode: false, 
        logFileChanges: true,
        logLevel: 'debug',
        open: true        
    });
    gulp.watch(...);
});

gulp.task('deploy',['build:prod'], function(){
    return gulp.src('./_site/**/*')
        .pipe(ghPages());
});