Local testing of existing GitHub Jekyll site

I want to locally test this GitHub Pages site: GitHub - opengenomebrowser/opengenomebrowser.github.io: Tutorials, documentation and installation instructions for OpenGenomeBrowser). I followed these instructions. In brief, I did this:

$ sudo dnf install ruby ruby-devel openssl-devel redhat-rpm-config @development-tools
$ echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
$ echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
$ echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
$ source ~/.bashrc
$ gem install jekyll bundler

# download my code
$ git clone https://github.com/opengenomebrowser/opengenomebrowser.github.io.git && cdopengenomebrowser.github.io.git
$ ls -ahl
total 108K
drwxr-xr-x. 1 user user  212 30. Jun 17:09 .
drwxrwxr-x. 1 user user 1.9K 30. Jun 17:09 ..
-rw-r--r--. 1 user user  43K 30. Jun 17:09 404.html
drwxr-xr-x. 1 user user   48 30. Jun 17:09 admin
-rw-r--r--. 1 user user  317 30. Jun 17:09 _config.yml
drwxr-xr-x. 1 user user  162 30. Jun 17:09 documentation
-rw-r--r--. 1 user user 3.7K 30. Jun 17:09 favicon.svg
drwxr-xr-x. 1 user user  138 30. Jun 17:28 .git
-rw-r--r--. 1 user user    5 30. Jun 17:09 .gitignore
-rw-r--r--. 1 user user 6.6K 30. Jun 17:09 index.md
-rw-r--r--. 1 user user 4.1K 30. Jun 17:11 installation.md
-rw-r--r--. 1 user user  35K 30. Jun 17:09 LICENSE
drwxr-xr-x. 1 user user  584 30. Jun 17:09 media
drwxr-xr-x. 1 user user  342 30. Jun 17:09 tutorials

$ bundle install
Could not locate Gemfile
$ bundle exec jekyll serve
Could not locate Gemfile or .bundle/ directory

So I created a Gemfile according to StackOverflow question 59922335 and installed a few missing dependencies:

bundle add jekyll
bundle add jekyll-theme-slate
bundle add jekyll-commonmark-ghpages
bundle add webrick
bundle exec ~/bin/jekyll serve

Now, serve ran without complaints. But when I open the site on localhost, I only see the folder’s content!

Can anyone help me?

Found a solution: The Gemfile was bad. This is the one that worked for me:

source 'https://rubygems.org'

git_source(:github) do |repo_name|
  repo_name = "#{repo_name}/#{repo_name}" unless repo_name.include?("/")

gem 'github-pages', group: :jekyll_plugins

gem "webrick", "~> 1.7"

Followed by bundle update.

I never used Ruby, this seems like voodoo to me. I’d like to suggest adding additional instructions to Testing your GitHub Pages site locally with Jekyll - GitHub Docs .

This whole process added lots of files to the repository:

$ git status
Untracked files:
  (use "git add <file>..." to include in what will be committed)

I suppose none of them should be pushed?

Glad you worked it out!

Here’s my default .gitignore that will help reduce the amount of file’s and code that get tracked in Git:


The DS_Store element is for MacOS, so you can leave it in .gitignore add that to Git globally on your compuTer as well.

If you are going to be downloading Jekyll sites from various repos and need to maintain different versions, Ruby can get a little more complicated. That is why I have transitioned to using Docker. Here’s a full training video I created that shows you how to do that:

:package: Develop Jekyll websites in a container (including GitHub Pages)

:open_book: Here are the step-by-step docs

Finally, read the above mentioned docs if you are opening a new repo. The process is pretty much to create the dockerfile (if one does not already exist) and then all you have to do is modify the _config.yml file and perhaps run a bundle install and bundle update.

Hope that helps!

Thanks for the info. Actually, I initially tried docker-based installs but ran in to version-based troubles. Probably because I didn’t know about pages.github.com/versions.

Very professional video, btw! You’re a great narrator.

A few details I noticed:

  • Some of the commands in your repo contain “ instead of ". Might confuse some younglings.

  • The command bundle exec jekyll new --force --skip-bundle . overrides my 404.html, _config.yml and index.md, so it is not suitable to test existing gh-pages!

My solution to locally run existing gh-pages:

(If you use docker, simply replace podman with docker in all commands below.)

  1. Clone the repo, switch to the publishing source branch (usually gh-pages)
  2. Add a Dockerfile with this content:
# Create a github-pages container from a Ruby Alpine image
# Choose the ruby version according to https://pages.github.com/versions/
FROM ruby:2.7-alpine3.15

# Add Jekyll dependencies to Alpine
RUN apk update
RUN apk add --no-cache build-base gcc cmake git

# Install github-pages
RUN gem update bundler && gem install bundler webrick github-pages
  1. Add a Gemfile with this content:
source 'https://rubygems.org'

git_source(:github) do |repo_name|
  repo_name = "#{repo_name}/#{repo_name}" unless repo_name.include?("/")

gem 'github-pages', group: :jekyll_plugins

gem "webrick"
  1. Add .gitignore:
  1. Build the image: podman build --tag gh-pages .
  2. Run the image: podman run -it --rm --volume="$PWD:/srv/jekyll:Z" -w /srv/jekyll -p 4000:4000 gh-pages /bin/sh
  3. Within the container, run bundle exec jekyll serve --livereload --host
  4. Apply your changes
  5. Profit


If I commit and push the Gemfile, will this have an effect on the deployment?

Thank you for the feedback. However, I will push back a little. It is 100% suitable to working with GitHub Pages. If you are using an existing site, you do not run the jekyll new command because you already cloned a site so you don’t need to create a new one.

Here are the steps:

  1. Clone your GH Pages site
  2. Add the dockerfile per the version settings I document in the video and the readme of my repo
  3. Open the dockerfile per instructions
  4. Run bundle install and bundle update
  5. Start working with the repo

When people ask me to help debug their Jekyll sites, those are the steps I follow. Sometimes there are some quirks, like having to do a bundle add webrick or something like that, but it is that easy.

Modifying the gemfile and pushing is fine, but if you add items that GH Pages does not support, then that will be an issue.

By all means, do push back. :smile: I still don’t properly understand how this works.

My main question is this: My gh-pages repo contains no Gemfile, which is required for bundle install, right? Following your instructions, none was created. What am I missing?

@MrTomRod A Gemfile is just a tool to aid in dependency-management. If your local Ruby installation doesn’t have multiple versions of Jekyll (and its runtime dependencies), then you need not require a Gemfile (and therefore Bundler) at all.

You may simply run jekyll serve to start the local webserver and deploy your site locally. Prepending bundle exec is only required if there are multiple versions of a gem.

To emulate GitHub Pages (GHP) without a Gemfile, you need to uninstall all versions of jekyll gem and install just the GHP gem:

1 Like

Sorry to bother you once more. Here is the github repo with the Dockerfile:

With the resulting container, I get errors like these:

/srv/jekyll # jekyll serve --livereload --host
Configuration file: /srv/jekyll/_config.yml
/usr/local/lib/ruby/2.7.0/rubygems/dependency.rb:311:in `to_specs': Could not find 'jekyll-theme-slate' (>= 0) among 82 total gem(s) (Gem::MissingSpecError)
Checked in 'GEM_PATH=/root/.gem/ruby/2.7.0:/usr/local/lib/ruby/gems/2.7.0:/usr/local/bundle', execute `gem env` for more information
/usr/local/bundle/gems/jekyll-4.2.2/lib/jekyll/theme.rb:82:in `rescue in gemspec': The jekyll-theme-slate theme could not be found. (Jekyll::Errors::MissingDependencyException)

From within the docker, I tried a few variations:

gem uninstall jekyll
gem install jekyll -v 3.9.2
gem install jekyll-commonmark-ghpages -v 0.2.0
gem install jekyll-theme-slate -v 0.2.0
# gem install webrick


gem uninstall jekyll
gem install github-pages -v 226
# gem install webrick

All followed by jekyll serve --livereload --host

However, the result always looks like this:

Assuming you have set up the visual studio extensions and installed Docker, follow the steps in the link below, starting at step 4.

At step 7, do not run this command:

bundle exec jekyll new --force --skip-bundle .

Should work! Let me know if it doesn’t and I’m happy to take a look at the repo.

I don’t use visual studio, unfortunately. I’m creating and starting the containers manually.

I tried to follow the tutorial. Some notes on the steps, maybe this will make it clearer:

  1. Does not apply, using pre-existing repo
  2. Does not apply, using pre-existing repo
  3. I installed the latest docker on my Fedora linux
  4. git clone https://github.com/opengenomebrowser/opengenomebrowser.github.io.git && cd opengenomebrowser.github.io && git checkout local-serve-without-gemfile
  5. Option 2, Jekyll 3.X and Ruby 2.7.X
  6. ruby:2.7-alpine3.15
  7. Dockerfile, built using podman build --tag gh-pages .
FROM ruby:2.7-alpine3.15
RUN apk update
RUN apk add --no-cache build-base gcc cmake git
RUN gem update bundler && gem install bundler jekyll

Here is where I start diverging from your tutorial because I don’t want to create a new gh-pages site, merely serve my already-existing one:

  • I start the container like this: podman run -it --rm --volume="$PWD:/srv/jekyll:Z" -w /srv/jekyll -p 4000:4000 gh-pages /bin/sh
  • The following commands don’t work because there is no Gemfile: bundle install, bundle update, etc
  • You wrote bundle isn’t necessary and I can directly serve (jekyll serve --livereload --host, but this also doesn’t work as described earlier.
  • I tried different versions of jekyll as well as installing github-pages

My instructions work if you are cloning or creating, but if you are not using Visual Studio Code, as my tutorial requires, then I see what the problem is :-). Sorry I cannot help you further with that particular request. If you do decide to use VSC, then it works great!

your screenshots show there are markdown files still in there.

The screen shot a couple posts above this is what you see when you do jekyll serve? there should not be an index.md file, maybe your issue is the content of the files? what is the content of index.md? if it is what is in that repo then I think your issue is the md files don’t have front matter and are not being rendered - just copied as is. Then you don’t have an index.html file which makes webrick serve a directory listing rather than the index page.

@BillRaymond Thanks anyway!


The screen shot a couple posts above this is what you see when you do jekyll serve?

Yes, exactly.

there should not be an index.md file, maybe your issue is the content of the files? what is the content of index.md?

You can see the full repo here. But I know it works - on the real github-pages as well as in my successful hacky setup with my custom Gemfile.

Then you don’t have an index.html file which makes webrick serve a directory listing rather than the index page.

That seems to be the problem.

without the front matter I don’t see how jekyll could be processing the md into html. My guess is the functioning live site is an old build and if you make a new commit it will either break or the build will fail and the old build will still be what shows.

Try editing something on the index page and then see if it shows up on the live site.

I think jekyll is working fine for you, you just aren’t getting the md files output as html because they don’t have front matter.

I edited index.md and it worked! (I used my hacky setup to test.)


that doesn’t make sense, there is no front matter, jekyll should not be processing it from what I understand.

Try doing the same thing on your live GH site, could be something small so it isn’t noticeable to people.

I think you have something else going on that isn’t obvious. Could be the theme you are using but not sure that makes sense.

what was the output in the console for what you did above? paste the full text.

I also uploaded a change to the live website: I changed the slogan. It worked. Have a look here: https://opengenomebrowser.github.io/

I created a new branch on my github. Follow these steps to reproduce:

# download code
git clone https://github.com/opengenomebrowser/opengenomebrowser.github.io.git
cd opengenomebrowser.github.io
git checkout local-serve-with-gemfile

# build image
docker build --tag gh-pages .

# start container
docker run -it --rm --user "$(id -u):$(id -g)" --volume="$PWD:/srv/jekyll:Z" -w /srv/jekyll -p 4000:4000 gh-pages /bin/sh

# within container, run jekyll
bundle exec jekyll serve --livereload --host

on GH you are using an action to build the site, that action uses:

which is why your md files without front matter work.

Locally you would need to do the same thing which it looks like you are now?

I am not using actions so don’t know what you would need to do to get that to work.

But your core issue of seeing a directory listing of files instead of the actual index page has to do with the md files not having front matter and thus not being processed by jekyll - vanilla jekyll requires front matter for md files to be processed. So if you can use the same things in that action that GH pages is using then you should be able to get the same thing. But you need to make sure you are doing it the same way.