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
- type branch name
- click create branch
Switch branch: GitHub Repo » Settings » Branches
Note: the setting » branches will only show if you have 2 branches.
Configuration and Publishing to GitHub Pages
Assuming you have ruby installed already.
- Go to your project location
git clone https://github.com/USER/my-repo-name.git
cd my-repo-name
gem install bundler
bundle init
» Gemfile will be created after this commandvim 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/[email protected]
#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
git add --all
orgit add .
.- Commit the files:
git commit -m "commit jekyll theme"
. - 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