Ready-to-fork setup of Babel, Gulp and Jekyll for GitHub Pages. Showcase / Blog post about this repo.
- Fork the repo
npm installin the root directory to install Gulp and Babel locally.
npx 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
npx gulp jekyll and visiting http://localhost:4000
If you are happy, checkout the
master branch, merge the
dev branch, run
npx 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.
- Running Babel for transpiling the files for browsers 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. This gulp 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.