Link Search Menu Expand Document

How to publish jekyll just-the-docs theme to Github Pages?

It took me a while to work out the steps and workaround to publish my repo to GitHub Pages, as it kept failing when deploying. Here I summarise the steps for my own reference.

Table of contents

Local just-the-docs jekyll theme

Local installation and development, refer to jekyll and just-the-docs.

Create Repo on GitHub

Good to know

Newly created repo has 1 branch, here is where you create new branch

  1. type branch name
  2. click create branch

new-branch


Switch branch: GitHub Repo » Settings » Branches

Note: the setting » branches will only show if you have 2 branches.

switch-branch


Configuration and Publishing to GitHub Pages

Assuming you have ruby installed already.

  1. Go to your project location
  2. git clone https://github.com/USER/my-repo-name.git
  3. cd my-repo-name
  4. gem install bundler
  5. bundle init » Gemfile will be created after this command
  6. vim Gemfile

Upon open, you see only 2 lines in the file.

source "https://rubygems.org"
git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }

This documentation is to install just-the-docs theme, so we add below in Gemfile

source "https://rubygems.org"
git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
gem "github-pages", group: :jekyll_plugins
gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
gem "webrick", "~> 1.7"
gem "just-the-docs"

After Gemfile, then copy the developed local files to Github ready folder.

vim _config.yml

Open _config.yml

remote_theme: pmarsceill/just-the-docs@v0.3.3
#theme: just-the-docs

# I've tested using the actual theme, GitHub Pages build keep failing, still don't know why. 
# Use `remote_theme` instead

Also update below information on _config.yml

url: "user.github.io"
# OR, if you have custom CNAME already, you can use: url: "example.com"
baseurl: "/my-repo-name"

After all done, run

bundle install

Before pushing to remote Github, you can check locally too on http://127.0.0.1:4000/

bundle exec jekyll serve

You can browse site: http://127.0.0.1:4000/

bundle exec jekyll clean 

to clean cache files, so after checked locally, to purge the local cache.


Publish the entire project

  1. git add --all or git add ..
  2. Commit the files: git commit -m "commit jekyll theme".
  3. Push the files to github repo: git push.

In case of rejected due to fetch first?

You may see error message like this:

! [rejected]        gh-pages -> gh-pages (fetch first)
error: failed to push some refs to 'https://github.com/USER/repo.git'

Under the same directory, do:

git remote add origin https://github.com/USER/my-repo-name.git
    #You might see this: error: remote origin already exists.
    #Ignore and run the next command
git pull origin gh-pages 

Single files update and push to Github

If updated one file _config.yml, run below commands to push single file

git add _config.yml
git commit
git push