- Jekyll is the most popular static site generator.
- GitHub Pages hosts your jekyll sites for free under *.github.io.
- Gulp lets you automate your build process (minifying .css files, concatenating all .js files etc.).
I switched to using Jekyll for this blog yesterday and I love it. There are blog posts describing how to combine a subset of the above, but I could not find one for combining all four. However, each of these four components brings its own peculiarities to consider, so no blog post worked out of the box. Here is the solution that I ended up with:
I created a boilerplate repository for GitHub Pages with Gulp and Babel set up.
- Fork the repo
npm installin the root directory to install Gulp and Babel locally.
gulp jekyllto build the site with Babel and serve it with Jekyll afterwards. Visit http://localhost:4000 to see the blog.
master branch should only be used for deploying (see considerations below). For development, switch to the
dev branch. After implementing your changes, test them by running
gulp jekyll and visiting http://localhost:4000.
If you are happy, checkout the
master branch, merge the
dev branch, run
gulp to build the site into the project's root directory and push / deploy the new build to the
master branch on GitHub.
Note: You can skip Babel during development by changing
source: _dist to
source: src and running
jekyll serve in the root directory.
See the Jekyll docs for an explanation of the files and directories.
. ├── _layouts // built by gulp ├── _posts // built by gulp ├── js // built by gulp | ├── main.js // transpiled by Babel ├── index.html // built by gulp ├── src | ├── _layouts | ├── _posts | ├── js | ├── main.js // in ES6 | ├── index.html ├── _config.yml ├── gulpfile.js ├── package.json ├── README.md ├── .gitignore
. ├── _dist // built by gulp | ├── _layouts | ├── _posts | ├── js | ├── main.js // transpiled by Babel | ├── index.html ├── src | ├── _layouts | ├── _posts | ├── js | ├── main.js // in ES6 | ├── index.html ├── _config.yml ├── gulpfile.js ├── package.json ├── README.md ├── .gitignore
- Running Babel for transpiling the ES6 files into ES5 before each deployment of the site is not practical, so a build tool like Gulp that runs Babel automatically is a must.
- There is a jekyll-babel Jekyll plugin but you have to start each .js file with exactly
WebStorm does not like that and formats it wrongly every time. If you try to escape that block with
// @formatter:off, the Jekyll plugin won't work anymore. Also, it is a bit dirty to mess with the .js files. If I want to directly run them during development, they will error. So, Babel has to be called by Gulp.
- Babel will generate the transpiled .js files somewhere. I don't want these files to mingle with the actual source .js files - that would cause confusion. So, using a
_distdirectory (ignored by git) would be clean. Jekyll can then generate the static site in
_siteby using the files in
- You have to commit all files that Jekyll needs to the
masterbranch on GitHub. So
_distmust not be ignored by git. At the same time it is generated code so it should be ignored. A solution is to ignore
devbranch. Then, merge the
devbranch to the
masterbranch, run Gulp and push the newly
_distto the GitHub
- For running Jekyll on the
_distdirectory, you would have to specify
source: _distin Jekyll's
_config.yml. However, GitHub overrides the
sourcesetting, which you cannot change (GitHub docs). So Jekyll's source directory has to be the repo's top level directory (for username.github.io pages). You also must commit the page to the
masterbranch. The solution is to keep the
source: _distsetting for the
devbranch, but let gulp build the site into the root directory on the
master, Gulp cannot clean the build directory before building because it is the project's root directory.
- You have to go to
master, build and push for every deployment of the site. The
gulp-gh-pagesgulp plugin might help with that.
master, I had to change
gulpfile.jsto make Gulp build into the root directory. Thus, changes to these files in
devwill have to be merged manually with master.