slush-gh-pages

GitHub Pages Generator (w/Slush)

A Slush generator for GitHub Pages that provides robust tooling for creating sophisticated Jekyll-based static websites.

[A Ronik Design creation.]

Goals

The goal of this project is to make it incredibly easy to get up-and-running with a GitHub Pages site that goes beyond the simple templates they offer. This generator has incorporated many of the best practices for building Jekyll-based sites, and adds in a number of helpful, Node.js-based development tools, as well as an easy selection of a CSS framework (Concise.css, Bootstrap v4, Bootstrap v3) and if using Bootstrap v3, Bootswatch themes. All is set up in a way that treats the framework and theme as a starting point that is easy to expand upon. You can also use it with no framework at all, just the stub directories and build tools.

A key focus is on simplicity, so in general the only commands you'll need to use in your project are npm start and npm run deploy. npm start will launch your local development environment, and watch your JS, SCSS, image and icon assets for changes to automatically recompile them, and npm run deploy aliases npm version minor and will increment your version identifier and commit your project to your GitHub repository, effectively deploying the latest version of your site.

Requirements

First prepare your environments. You will need:

• Ruby environment, and a working. [Note: Ruby v2.4.0 is not yet working]
• Node.js environment.

Plus, some global packages for those environments.

• Bundler Ruby Gem
• Slush npm module

Details might vary, but that should be as easy as running these commands:

[sudo] gem install bundler
npm install slush slush-gh-pages --global

Install

Now, clone the GitHub repo you want to set up with Pages and run:

cd [REPO_DIR]
git checkout -b gh-pages
slush gh-pages

GitHub provides several options for the location of your GitHub Pages source. the gh-pages branch has been around the longest. See: User, Organization, and Project Pages

Running npm start after you've generated without a git repo in the working directory can result in some warnings. You've been warned.

What you get

• npm start - launch watchers, start serving your site locally, auto-reload with Browser Sync
• npm run deploy - create production builds of your assets, increment the version tag, and push to GitHub. Alias for npm version minor which you can also use.
• _assets/javascripts - build your JS app using ES2015 (at Stage 0, so some ES7 as well), Babel (with transform-runtime handling polyfills), Uglify, Webpack and any selected framework libraries. Configure your build in the generated webpack.config.js.
• _assets/stylesheets - build your stylesheets using SCSS, PostCSS and any selected frameworks. Configure your PostCSS build in the generated postcss.config.js.
• _assets/images - any images here will be automatically optimized via imagemin.
• _assets/images/icons - any svg files placed here will automatically be compiled into a svg-sprite.
• _layouts/compress.html - the Jekyll HTML compressor
• package.json - build and watch scripts.
• Gems - all the github supported plugins are enabled, giving you some great features
  • the github-pages Ruby gem, replicating the deployed environment locally
  • jekyll-mentions
  • jemoji
  • jekyll-redirect-from
  • jekyll-sitemap
  • jekyll-feed
  • jekyll-seo-tag
  • jekyll-paginate
  • jekyll-gist
  • jekyll-github-metadata

Q&A

In lieu of real documentation, just be prepared to answer the following questions. Sensible defaults are offered where available, read either from your system and directory, or a pre-existing package.json or _config.yml.

• GitHub repo name? This is required. [e.g. foo/bar, https://github.com/foo/bar.git]
  • Because some of the GitHub Pages modules will fail without this, and I think they are important for the whole process, please have this ready, even if you haven't added any files to your repo just yet.
• Branch for GitHub Pages? [For Travis CI config]
  • This is often gh-pages but GitHub has a number of other options
• GitHub token?
  • This is strongly suggested for several of the default plugins to function correctly
  • Suggested permissions are 'public_repo' and 'gist'.
  • See: Creating an access token for command-line use
• What is the PRETTY name of your site?
• What is the name SLUG for your site?
• What is the url for your site?
• What is the hostname for your site? [Leave blank if not using a custom domain]
  • This will create or modify your CNAME file for a custom domain.
• Who is authoring the site?
  • Just the author's name.
• What is the author's email address?
• Twitter username?
  • jekyll-seo-tag is installed by default, and can make use of this.
• Please describe your site.
• What is the timezone for your site?
  • This will detect your system TZ as the default.
• What is the version of your site?
  • Detected from an existing package.json
• Which permalink pattern would you like to use?
  • See: jekyll permalink style
• Which CSS & JS framework would you like to use?
  • Blank — just some stub files and directories.
  • Concise.css
  • Bootstrap v4
  • Bootstrap v3
• If you chose Bootstrap v3 you will also have the option to select a Bootswatch
• Deploy after intstall?

Nice to know

Feel free to run this generator multiple times, or over a GitHub Pages project you've already started working on, but where you think some of the tools here might come in handy. During the Q&A phase you'll have many defaults provided based on reading your system env and any existing package.json _config.yml and _data/authors.yml files in your current directory.

After the Q&A you will be prompted for a conflict resolution for any file that would be modified by the generator. You need to be very careful here, since you could overwrite work you want to keep.

Installation problems

• Sometimes the nokogiri dependency will fail to build if you don't have your Xcode tools properly installed. Be sure to try xcode-select --install. If that doesn't work check this thread for more possible fixes.

Credit

Created by Michael Shick for Ronik Design to ease the creation of simple static sites.