local-github-pages

Set up an environment to preview your github-pages locally

Unlike the half-baked guide on official docs, this repository provides a "setup once, use anywhere" environment for previewing github pages locally.

The generated preview closely matches GitHub's deployment runner, with negligible differences in a few {{ site.github }} properties. All page themes and plugins listed in github pages dependencies come bundled with the initial setup. This includes QoL plugins such as jekyll-github-metadata, jekyll-optional-front-matter, etc.

While most plugins in the said list are loaded by default on github pages, some need to be explicitly enabled via the plugins: list in _config.yml.

Initial Setup

1. Make sure ruby, gem and bundler are installed

   sudo apt install ruby ruby-dev build-essential

   gem install bundler

   (or download from ruby-lang.org)
2. Clone this repo, then run bundler to install dependencies locally

   bundle install

3. Optional: Copy example.env to .env and edit the values. This step deals with repo naming and github API calls

   cp example.env .env

Usage

To start the local server, run jekyll with --source flag with directory path of the repo you want to preview:

bundler exec jekyll serve --livereload --source ../your/repo/path

Or use runserver.sh which is a simple wrapper around that long command:

./runserver.sh ../your/repo/path

The path defaults to the current directory if not specified.

Important

For resolving the repo name and github metadata variables, .env needs to be configured as mentioned in step 3 of the setup.

NEVER commit your API tokens to the public!

Updating Version

To update to the latest Github Pages version, run bundler's update command:

bundler update github-pages

For further information or troubleshooting, refer to the documentation on Github Pages gem.