I am using github-pages with a remote theme (just-the-docs) to host one of my projects' documentation. I wanted a way to test everything locally, without having to install anything on my machine. I found lots of resources, including this dev.to post, but none worked as expected. My biggest problems were:

• the remote_theme key in _config.yaml was either ignored or throwing errors,
• the navigation and all the links pointed to github.io instead of localhost (maybe due to my theme),
• the local rendering was quite different from what GitHub deploys.

Here is how I finally managed it.

Required files

Apart from the usual _config.yml, you need two files: Gemfile and _config_dev.yml (and a .gitignore).

# github-pages mandatory configuration
domain: derlin.github.io
url: https://derlin.github.io
baseurl: /docker-compose-viz-mermaid/
repository: derlin/docker-compose-viz

# name of the theme I use (add https://github.com/ to get the actual link)
remote_theme: pmarsceill/just-the-docs

# ... other configuration ...

The Gemfile just installs github-pages and kramdown (to parse GFM). It is using the latest version at the time of writing (219), but check dependency version for updates:

source "https://rubygems.org"

# do NOT include the Jekyll gem !
gem "github-pages", "~> 219", group: :jekyll_plugins
gem "kramdown-parser-gfm"

When the site runs locally, it is important to override the url to point to localhost instead of github.io. To do this, create another file, _config_dev.yml with only:

url: http://localhost:4000

Finally, add a .gitignore at the root of the docs folder with the following:

_site
Gemfile.lock
.bundles_cache

Running without Docker

If you have ruby/gem and Jekyll installed locally, you just have to do the following:

# update bundler
gem install bundler
# do this once to install the gems
bundle install
# then run the server (overriding the base url)
bundle exec jekyll serve --config "_config.yml,_config_dev.yml"

Running inside Docker

If like me you do not want to install ruby and Jekyll, Docker is here at the rescue.

Create jekyll.sh at the root of your docs folder (where _config.yml is located), and paste the following:

#!/usr/bin/env bash

# using the official Jekyll image, see https://github.com/envygeeks/jekyll-docker
# runs on port 4000


mkdir -p ".bundles_cache"
docker run --rm \
  -v "$PWD:/srv/jekyll" \
  -e BUNDLE_PATH="/srv/jekyll/.bundles_cache" \
  -p 4000:4000 \
  jekyll/builder:3.8 \
  bash -c "gem install bundler && bundle install && bundle exec Jekyll serve --host 0.0.0.0 --verbose --config _config.yml,_config_dev.yml"

The .bundles_cache directory is used to cache the installed bundles on the host, so the container starts faster the next time (as bundle install may take a while). Jekyll itself is started in verbose mode, feel free to change it.

Note that jekyll serve will watch your directory, and recompile the site on every change. Perfect for development.

The full example can be found here.

Written with ❤ by derlin