DEV Community

Lucy Linder
Lucy Linder

Posted on

Testing github pages with remote theme locally

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 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 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).

My _config.yml file for reference
My _config.yml has the following content:
# github-pages mandatory configuration
baseurl: /docker-compose-viz-mermaid/
repository: derlin/docker-compose-viz

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

# ... other configuration ...
Enter fullscreen mode Exit fullscreen mode

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 ""

# do NOT include the jekyll gem !
gem "github-pages", "~> 219", group: :jekyll_plugins
gem "kramdown-parser-gfm"
Enter fullscreen mode Exit fullscreen mode

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

url: http://localhost:4000
Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Running inside Docker

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

Create 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
# 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 --verbose --config _config.yml,_config_dev.yml"
Enter fullscreen mode Exit fullscreen mode

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

Discussion (0)