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
).
My _config.yml file for reference
My _config.yml
has the following content:
# 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
Top comments (0)