Testing github pages with remote theme locally
Tags: testing, local, githubpages, docker
Published: 2021-09-29 18:27:25

I am using github-pages with a remote theme ([just-the-docs](https://github.com/pmarsceill/just-the-docs)) to host [one of my projects' documentation](https://derlin.github.io/docker-compose-viz-mermaid/). 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](https://dev.to/dillonad/testing-github-pages-locally-agf), 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`).

{% collapsible My _config.yml file for reference %}
My `_config.yml` has the following content:
```yaml
# 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 ...
```
{% endcollapsible %}

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](https://pages.github.com/versions/) for updates:
```ruby
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:
```yaml
url: http://localhost:4000
```

Finally, add a `.gitignore` at the root of the docs folder with the following:
```text
_site
Gemfile.lock
.bundles_cache
```

## Running without Docker

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

```bash
# 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:

```bash
#!/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](https://github.com/derlin/docker-compose-viz-mermaid/tree/7789bb762df6d8534e2e56e409993373334fd83a/docs).

-----------

Written with ❤ by [derlin](https://github.com/derlin)