title | layout |
---|---|
Jekyll versioning workflows |
page |
ย
You have two options when it comes to host a Jekyll site on Github pages :
- simple versioning : your code is in one repository branch
- multi-branch versioning : code and site in two separate branches
You just have to ask few questions :
- do I need plugins to render my site ?
- do I need extra processing like Gulp task or Rake tasks ?
- do I need to push in several locations (integration, continuous integration) ?
If the answer to any of this questions is yes then you should use multi-branch versioning. Otherwise, stay with the basic versioning.
You host your site on Github pages and just have to push your code :
- in master branch for user repository at https://github.com/userName/userName.github.io (url : http://userName.github.io)
- in gh-pages branch for project repositories at https://github.com/userName/repositoryName (url : userName.github.io/projectName).
Just need a git push origin master
or git push origin gh-pages
and Github will build you site just fine.
This is the simplest versioning worflow.
If you need some plugins (generator, tag, ...) or build tasks (gulp, grunt, ...) they will not run on gh-pages. So, you will have to build you site before pushing the resulting pages on github (or on any server that can serve static pages).
For a User/Organization site, it will be master branch for the site build, and sources branch (or any name you like) for the code. It will be versioned at github.com/userName/userName.github.io and hosted at https://userName.github.io.
For a Project site, it will be gh-pages branch for the site build, and master branch (or any name you like) for the code. A Project site will be versioned at github.com/userName/projectName and hosted at https://userName.github.io/projectName.
Both repository can also have a custom domain name, but it's another story.
Check out the Rakefile !
It can do :
- base install with multi-branch versionig
- launch build tasks (rake, gulp)
- deploy code to various locations (local, continuous integration, production)
- order pizzas
In order to publish :
- a User/Organization site : source code will be versioned in a source branch and site code in master branch.
- a Project site : source code will be versioned in a source branch and site code in gh-pages branch.
Once you've set the parameters in the head of the Rakefile, you can launch the installation by doing :
-
create a repository on github (eg: https://github.com/userName/userName.github.io)
-
in the console do
cd pathTo/yourJekyllSource
-
then
wget https://raw.githubusercontent.com/djacquel/JekyllVersioningWorkflows/master/Rakefile
will save the Rakefile in your repository. -
be sure that you have the push permission on the Github repository
-
edit the Rakefile and set parameters.
-
in the console do :
rake setup
And it's done !
In the background, and depending if we deal with a User/Organization (UO) site or a Project site (P), rake setup
does :
-
git init
-
git remote add origin [email protected]:userName/userName.github.io.git
(UO) orgit remote add origin [email protected]:userName/repositoryName.git
(P) -
jekyll new .
creates your code base -
in _config.yml, set the baseurl parameter to baseurl: '' (UO) or baseurl: '/repositoryName' (P)
-
in .gitignore add _site, it will be versioned in the other branch
-
jekyll build
will create the destination folder and build site. -
git checkout -b sources
(UO) orgit checkout master
(P) -
git add -A
-
git commit -m "jekyll base sources"
commit your source code -
git push origin sources
(UO) orgit push origin master
(P) push your sources in the appropriate branch -
cd _site
-
touch .nojekyll
, this file tells gh-pages that there is no need to build -
git init
init the repository -
git remote add origin [email protected]:userName/userName.github.io.git
(UO) orgit remote add origin [email protected]:userName/repositoryName.git
(P) -
git checkout master
(UO) orgit checkout -b gh-pages
(P) put this repository on the appropriate branch -
git add -A
-
git commit -m "jekyll first build"
commit your site code -
git push origin master
(UO) orgit push origin gh-pages
(P)
- rake build : Build Jekyll with production configuration
- rake deploy : Deploy code and site in appropriate branches on Github
- rake dev : Build Jekyll with development configuration
- rake list : list tasks
- rake setup : Do the base setup for a repository with complex workflow
- rake w : Build Jekyll with development configuration and watch
Feel free to fork my repository if you want to enrich the code.