$ 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:
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)
.sass-cache/
Gemfile
Gemfile.lock
README.md
Rakefile
_site/
app/
bin/
config.ru
config/
db/
lib/
log/
package.json
public/
test/
tmp/
vendor/
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:
Develop Jekyll websites in a container (including GitHub Pages)
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.
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.)
Clone the repo, switch to the publishing source branch (usually gh-pages)
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
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?("/")
"https://github.com/#{repo_name}.git"
end
gem 'github-pages', group: :jekyll_plugins
gem "webrick"
Add .gitignore:
_site
.sass-cache
.jekyll-metadata
Gemfile.lock
Build the image: podman build --tag gh-pages .
Run the image: podman run -it --rm --volume="$PWD:/srv/jekyll:Z" -w /srv/jekyll -p 4000:4000 gh-pages /bin/sh
Within the container, run bundle exec jekyll serve --livereload --host 0.0.0.0
Apply your changes
Profit
Question
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:
Clone your GH Pages site
Add the dockerfile per the version settings I document in the video and the readme of my repo
Open the dockerfile per instructions
Run bundle install and bundle update
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. I still don’t properly understand how this works.
My main question is this: My gh-pagesrepo 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:
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 0.0.0.0
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)
...
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:
Does not apply, using pre-existing repo
Does not apply, using pre-existing repo
I installed the latest docker on my Fedora linux
git clone https://github.com/opengenomebrowser/opengenomebrowser.github.io.git && cd opengenomebrowser.github.io && git checkout local-serve-without-gemfile
Option 2, Jekyll 3.X and Ruby 2.7.X
ruby:2.7-alpine3.15
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 0.0.0.0), 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.
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.
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.
Develop Jekyll websites in a container (including GitHub Pages)
Here are the step-by-step docs
I still don’t properly understand how this works.
