README
jekyll-postcss-browserify
A boilerplate for building static websites with Gulp, Jekyll, PostCSS, Browserify, imagemin, svg-sprite, and more.
This project is an opinionated front-end boilerplate for developing and deploying static websites using Jekyll. It includes several front-end tools that help facilitate the development process, and Gulp to automate common development tasks, compiling source code, watching files for changes, and deployment.
Features
- Gulp as a build system to automate tasks, compile source code, watch files for changes, and deployment.
- Jekyll as a blog-focused static site generator that uses the Liquid templating language.
- PostCSS for CSS file imports, url rebasing, future-friendly syntax, vendor prefixing, and more.
- Browserify for requiring JavaScript modules and bundling dependencies in the browser.
- imagemin for compressing image files.
- svg-sprite to automatically generate and optimize an SVG sprite from raw SVG icon files.
- Browsersync with xip.io for serving files, live-reloading browsers, and multi-device testing.
Requirements
This project is compatible with Linux, Unix, and Mac OSX operating systems. It requires the following software to be already installed on your system:
Running Windows? Jekyll does not officially support the Windows operating system, but they do provide special instructions if you want to take a crack at it anyway.
Installation
Clone this repository to your local machine, and install its dependencies with the following command(s):
git clone git@github.com:cbracco/jekyll-postcss-browserify.git
cd jekyll-postcss-browserify/
npm install
The npm install
command will first run bundle install
to install the required Ruby gems, and then npm install
for the required npm modules.
Usage
Developing
To start working, first run the following command(s):
npm start
The npm start
command will run the default Gulp task which builds the Jekyll templates and compiles the website assets, starts a local server (http://127.0.0.1.xip.io:9999) with Browsersync, opens the project in the default browser, and begins watching for file changes.
This is considered “Development Mode”, which means that the files being served in this local environment are not yet minified or optimized for deployment.
Publishing
To publish a production-ready version of the website, run the following command(s):
npm run production
The npm run production
command will run the production Gulp task which deletes any existing production builds, builds a new production-ready version of the website, starts a local server (http://127.0.0.1.xip.io:9998) with Browsersync, and opens the project in the default browser.
This can be considered “Production Mode”, which means that the files being served in this local environment are minified and optimized for deployment. It is intended to mimic the production environment on your local environment, so you can preview exactly what you will see before you deploy the website to a production server.
Deploying
Before deploying the website, first create a file called rsync-credentials.json
and fill it with the following information:
{
"destination": "/path/to/your/website",
"hostname": "example.com",
"username": "person",
"port": 666
}
Then, run the following command(s) to deploy a production-ready version of the website to a remote server:
npm run deploy
The npm run deploy
command will run the deploy Gulp task which deletes any existing production builds, builds a new production-ready version of the website, and uses rsync to upload the website to the specified remote server.
Credits
“If I have seen further it is by standing on ye sholders of Giants.” — Issac Newton
jekyll-postcss-browserify is a project by @cbracco and its contributors. It is influenced by the following organizations, projects, articles, and individuals:
Thank you all for your hard work.