CODEWITHSUNDEEP
githubjekyllgithub-pages
thatryan
thatryan

Reputation: 1559

Deploying Jekyll to Github Pages

I have built a site locally with Jekyll, and have pushed it to a new master repo (username.github.com) and the site works great yay. My question is, how do I move just the deployable part, the _site directory, into a gh-pages branch? Or rather, the contents of that directory if that is the best way to deploy?

I plan on using a custom domain. My workflow will be to work in the master branch, maybe some feature branches, and then push (merge) the compiled outcome into the gh-pages branch. Does that sound correct?

I am having a tough time figuring it out via documentation, would appreciate any help, thank you!

Upvotes: 20

Views: 9755

Answers (6)

Kleber Germano
Kleber Germano

Reputation: 770

Despite of GitHub pages build automatically you could deploy only the static files to the branch gh-pages, the main purpose of do something like this is to run third party plugins; todo so, I created a script to help in the proccess of do it.

If you prefere download the script here

What this script does is:

Default names of the folders:
BUILD_FOLDER='_site'
PUSH_FOLDER='_site_ghpages'

  1. It creates a folder with the seted name in PUSH_FOLDER. / Clean it if the folder alredy exists;
  2. Change the directory to the PUSH_FOLDER (cd $PUSH_FOLDER);
  3. Clone only the remote branch gh-pages of GitHub to PUSH_FOLDER;
  4. Copy all the content of the BUILD_FOLDER to the PUSH_FOLDER;
  5. Add all the files of PUSH_FOLDER in the local branch gh-pages, commit and push to the remote gh-pages;
  6. Go back to the previouly directory.

How to use it:

First make sure of:

  1. Ignore the PUSH_FOLDER in the .gitignore file;
  2. Already have a branch called "gh-pages" created in your repository (After run the script this branch will have only the static files of the build folder).

To execute the script first you should allow it to run as a executable in your machine, to do so, with Bash/Git Bash run:

chmod +x push_ghpages.sh

After that just run the file calling:

. push_ghpages.sh

When called without argument the scirpt push with a 'Automatic commmit' message. So if you want to set your commit message just pass it as a argument, like this:

. push_ghpages.sh "Your commit message goes here."

If you have any problem while execute, just delete the PUSH_FOLDER, empty the remote gh-pages and let the script rebuild e push the content.

Also enter the PUSH_FOLDER cd my_push_folder_directory and run a git branch to check if it have ONLY the branch gh-pages, if it have a master branch or any other, delete it.

#! /bin/bash
# Author: [email protected]
# This is a script used to automatically deploy a Jekyll website/blog with third party plugins to GitHub Pages.

BUILD_FOLDER="_site";
PUSH_FOLDER="_site_ghpages"; 
COMMIT_MESSAGE=$1

#Remove all the content from the "PUSH_FOLDER".
function removeAllContentFromPushFolder(){
    rm -r $PUSH_FOLDER/*;
}

#Create the folder "PUSH_FOLDER".
function createFolderToPush(){
    mkdir $PUSH_FOLDER
}

#Copy all the content from the folder _site to PUSH_FOLDER.
function copySiteToFolder(){
    cp -r $BUILD_FOLDER/. $PUSH_FOLDER
}

#Clone only the branch "gh-pages" to the folder "PUSH_FOLDER". 
function cloneGhpages(){
    git clone --branch gh-pages `git config remote.origin.url` $PUSH_FOLDER
}

function prepareThePushFolder(){
    if [[ -d ./$PUSH_FOLDER ]]
    then
        #Remove all the content from the folder "PUSH_FOLDER".
        removeAllContentFromPushFolder
    else
        #Create the folder "PUSH_FOLDER" if it doesn't exist.
        createFolderToPush
        #Call the function that clone the branch "gh-pages" to the folder "PUSH_FOLDER". 
        cloneGhpages
        #Remove any prevous content from the folder "PUSH_FOLDER".
        removeAllContentFromPushFolder

    fi
    #Call the function that copy all the content from the folder _site to "PUSH_FOLDER".
    copySiteToFolder
}

function changeDirectoryToGhpages(){
    cd $PUSH_FOLDER
}

function setMessageCommit(){
    if ! [ "$COMMIT_MESSAGE" ]
    then
      COMMIT_MESSAGE='Automatic Commit'
    fi
}

function pushBranchGhpages(){
    git add .
    git commit -m "$COMMIT_MESSAGE"
    git push
}

function changeDirectoryBack(){
   cd ..
}

prepareThePushFolder
changeDirectoryToGhpages
setMessageCommit
pushBranchGhpages
changeDirectoryBack

Upvotes: 1

andimiya
andimiya

Reputation: 539

Your workflow should be to work in a development or feature branch, then push ONLY the built files to your master branch for them to be served by Github Pages.

To do this:

  1. Start in your development branch with all your changes ready to be built and made live.
  2. Run in your development branch: rm -rf _site (this will remove old built files to the _site folder)
  3. Run git clone -b master 'git config remote.origin.url' _site (this will create a master branch for your built files)
  4. Run jekyll build (build your site)
  5. cd _site
  6. If you have a custom domain, do 7-8, otherwise skip to step 9
  7. touch CNAME
  8. Add your custom domain to that CNAME file
  9. git add . (you should be in the master/_site branch now)
  10. git commit
  11. git push

Now, only your built files should be on master, your working files will be on your development or feature branch!

I struggled with this for a while, so built a script if you'd like to use it: https://github.com/andimiya/deploy-jekyll-gh-pages

Upvotes: 3

yegor256
yegor256

Reputation: 105043

Try my jgd gem. All you need to do is to install it and run:

gem install jgd
jgd

Done! Your site is built and deployed to gh-pages. Also jgd perfectly integrates with travis-ci or any other CI server.

This post explains the mechanism in details: http://www.yegor256.com/2014/06/24/jekyll-github-deploy.html

Upvotes: 3

akajut
akajut

Reputation: 31

You do not want to make any changes to the files in the folder _site. _site is were Jekyll saves the static html pages it generates. They will be automatically overwritten the next time the Jekyll server regenerates the site. For example if you create a new blog post, the server sees the new file (or updated file), and then the server regenerates the static pages with the new content in them. This is how your new blog post is at the top of the page.

It is considered a best practice to add _site to your .gitignore file. There is no need to push that directory to your repo, since it will be overwritten as soon as they hit github's servers.

I think what you want to do is checkout a new branch, make changes, and then merge that into the gh-pages branch.

Upvotes: 1

mattr-
mattr-

Reputation: 5821

Your workflow does not sound correct based on the details in your question.

If you have pushed your Jekyll-based site to a username.github.io repository, then you do not need a gh-pages branch. A gh-pages branch is only required for repositories where you want to have code and a website in the same repository. GitHub Pages will take care of running Jekyll for you and serving the compiled site in both cases.

GitHub Pages does run Jekyll in a very specific manner in order to keep it safe. If you're using custom plugins with your Jekyll site, then you'll need to store your compiled site (the _site directory you mentioned) on the master branch, and the source in a different branch.

To summarize, your workflow should be work in your local repository - either in the master branch or feature branches (merging the feature branches to your local master branch as needed) - and when you're ready to publish, push your local repository to the master branch on GitHub.

Upvotes: 18

Aniket
Aniket

Reputation: 9758

What you wish to do is very similar to how Octopress works. Let me explain to you how you can do something like this.

You wish to deploy the data which is present in _site to the branch gh-pages. So, your first step will be to make the default branch for your repository username.github.com to be gh-pages and not master or source (basically whatever you want it to be). What you need to do now is write tasks in your Rakefile that copy the contents of _site to branch gh-pages. Once that is done, you can automate the push procedure or do it manually. That way, GitHub will not build your website when you push your default branch, instead it will just server the static pages that are present in _site.

If you want to understand how the scripts work, you should take a look at the Rakefile present in Octopress. It has these two tasks called as generate and deploy. When you run rake generate, it will run jekyll --no-auto with parameters for putting the code into a directory called _deploy and when you run rake deploy, it copies the content of _deploy to branch gh-pages and makes commit. Personally, I like this procedure a lot but I haven't implemented it in my Jekyll site as such.

Upvotes: 3

Related Questions