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:
_config.yamlwas 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.
Apart from the usual
_config.yml, you need two files:
_config_dev.yml (and a
My _config.yml file for reference
_config.yml has the following content:
# github-pages mandatory configuration
# name of the theme I use (add https://github.com/ to get the actual link)
# ... other configuration ...
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:
Finally, add a
.gitignore at the root of the docs folder with the following:
_site Gemfile.lock .bundles_cache
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"
If like me you do not want to install ruby and Jekyll, Docker is here at the rescue.
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"
.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.
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