Anyone with read permissions for a repository can test a site locally.

Prerequisites

Before you can use Jekyll to test a site, you must:

• Install Jekyll.
• Create a Jekyll site. For more information, see "AUTOTITLE."

Building your site locally

1. Run bundle install.

2. Run your Jekyll site locally.

   $ bundle exec jekyll serve
   > Configuration file: /Users/octocat/my-site/_config.yml
   >            Source: /Users/octocat/my-site
   >       Destination: /Users/octocat/my-site/_site
   > Incremental build: disabled. Enable with --incremental
   >      Generating...
   >                    done in 0.309 seconds.
   > Auto-regeneration: enabled for '/Users/octocat/my-site'
   > Configuration file: /Users/octocat/my-site/_config.yml
   >    Server address: http://127.0.0.1:4000/
   >  Server running... press ctrl-c to stop.

   Notes:

   • If you've installed Ruby 3.0 or later (which you may have if you installed the default version via Homebrew), you might get an error at this step. That's because these versions of Ruby no longer come with webrick installed.

     To fix the error, try running bundle add webrick, then re-running bundle exec jekyll serve.

   • If your _config.yml file's baseurl field contains your GitHub repository's link, you can use the following command when building locally to ignore that value and serve the site on localhost:4000/:

     bundle exec jekyll serve --baseurl=""

3. To preview your site, in your web browser, navigate to http://localhost:4000.

Updating the gem

Jekyll is an active open source project that is updated frequently. If the github-pages gem on your computer is out of date with the github-pages gem on the server, your site may look different when built locally than when published on . To avoid this, regularly update the github-pages gem on your computer.

1. Update the github-pages gem.
   • If you installed Bundler, run bundle update github-pages.
   • If you don't have Bundler installed, run gem update github-pages.

Further reading

• in the Jekyll documentation