Directory Structure for Jekyll / GitHub Pages with Gulp and Babel

• 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.).
• Babel lets you write ES6 (cool new JavaScript) even though not all browsers support it by transpiling it into ES5 (lame old JavaScript).

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:

Result

I created a boilerplate repository for GitHub Pages with Gulp and Babel set up.

Usage

1. Fork the repo
2. Run npm install in the root directory to install Gulp and Babel locally.
3. Run gulp jekyll to build the site with Babel and serve it with Jekyll afterwards. Visit http://localhost:4000 to see the blog.

Development

The 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.

Directory Structure

See the Jekyll docs for an explanation of the files and directories.

On master

.
├── _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

On dev

.
├── _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

Considerations

• 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 src and a _dist directory (ignored by git) would be clean. Jekyll can then generate the static site in _site by using the files in _dist.
• You have to commit all files that Jekyll needs to the master branch on GitHub. So _dist must not be ignored by git. At the same time it is generated code so it should be ignored. A solution is to ignore _dist on the dev branch. Then, merge the dev branch to the master branch, run Gulp and push the new _dist to the GitHub master branch.
• For running Jekyll on the _dist directory, you would have to specify source: _dist in Jekyll's _config.yml. However, GitHub overrides the source setting, 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 master branch. The solution is to keep the source: _dist setting for the dev branch, but let gulp build the site into the root directory on the master branch (docs).

Drawbacks

• On 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-pages gulp plugin might help with that.
• On master, I had to change _config.yml and gulpfile.js to make Gulp build into the root directory. Thus, changes to these files in dev will have to be merged manually with master.

You can also leave a comment if you have a GitHub account. The "Sign in" button will store the GitHub API token in a cookie.