Confused with paths running jekyll website locally

I host my website on GitHub Pages so I used site.github.url in my URL's (as it is described in documentation). Like this:

<a href="{{ page.url | prepend: site.github.url }}">{{ page.title }}</a>

in documentation it is also said that

This way you can preview your site locally from the site root on localhost, but when GitHub generates your pages from the gh-pages branch all the URLs will resolve properly.

Now I try to preview it locally, but all the links have http://my-username.github.io/ in front of them.

What am I doing wrong? Maybe I am missing something?

Solution

Locally you can use a _config_local.yml to override default URL value.

Add this in your _config_local.yml:

github:
  url: http://localhost:4000

And then you can launch Jekyll and ask to parse both config files like this:

bundle exec jekyll build --config _config.yml, _config_local.yml

and

bundle exec jekyll serve --config _config.yml,_config_local.yml

Optional: You can alias the command or use rake to launch tasks.

Add the rake gem to your Gemfile:

group :development do
  gem 'rake'
end

Install with bundle install

Create a Rakefile:

touch Rakefile

Copy this content in your Rakefile:

require 'jekyll'

task :build do

options = {
  'trace'       => true,
  'verbose'     => true,
  'config' => %w(_config.yml _config_local.yml)
}
Jekyll::Commands::Build.process(options)
end

task :serve do
options = {
  'serving'     => true,
  'watch'       => true,
  'incremental' => true,
  'config'      => %w(_config.yml _config_local.yml)
}
Jekyll::Commands::Build.process(options)
Jekyll::Commands::Serve.process(options)
end

Now you can use bundle exec rake build and bundle exec rake serve without having to pass options.