The Minimill project template is the best way to build static sites fast. With one command, build a static page using Gulp, Jekyll, and SCSS.
Other Versions: ES6, Minimill internal
- Install the project in just three commands (see "Developing" below).
- Use Jekyll for content management and templating.
- Use ImageMagick to resize images for responsive / retina loading.
- Use SCSS to keep our CSS organized into logical components.
- Use Autoprefixer to automatically insert browser prefixes where necessary to handle cross browser compatibility.
- Use Browsersync to automatically launch a development version of our website, reload the page whenever we change the HTML, and inject changes to CSS, JavaScript, and images with needing to reload.
- Use HTML Minifier, CSSNano, UglifyJS, and ImageMin to compress and optimize our HTML, CSS, JavaScript, and images, respectively.
- Use SCSS-Lint, JSHint, and JSCS to perform linting and style checking on our SCSS and JavaScript files.
All with one command from the terminal:
gulp serve
Install npm. Then, install gulp:
npm install -g gulp # May require `sudo`
Finally, install ImageMagick. You have done so successfully if you can run
convert -help
without any errors.
npm install # One time
gem install scss_lint # One time
gulp serve
Because Gulp and Jekyll to not play nice historically, static assets need to be generated into two different folders:
- SCSS source files live in
_scss/
and compile to bothcss/
and_site/css/
- JavaScript source files live in
_js/
and compile to bothjs/
and_site/js/
- Images in
_img/
compile to bothimg/
and_site/img/
Note: the root level
css/
,js/
, andimg/
folders are in the.gitignore
and are regularly deleted. Modifications to these folders may be lost without warning! Instead, edit source files in the corresponding underscore-prefixed folders.
Responsive images live in the /_img/res
folder. Place images that you wish to resize into the /_img/res/raw
folder. To resize them, run
gulp responsive
This will create subdirectories within the /_img/res/
folder with resized images in each. By default, it creates the folders 20/
, 200/
, 800/
, and 1600/
, with images resized to those heights in pixels in each one. Then, these images will be copied into /_site/img/res/<size>
for static access.
For example, if /_img/res/raw/test.png
has resolution 5120x3200, running gulp responsive
will create a 32x20px image at /_img/res/20/test.png
, a 320x200px image at /_img/res/200/test.png
, etc. After running gulp serve
, those files will be available statically at /img/res/<size>/test.png
. In addition, data about these images (filename / aspect ratio pairs, and generated sizes) is generated into /_data/responsiveMetatdata.json
.
You can customize what size images are generated by changing the responsiveSizes
variable at the top of Gulpfile.js
.
Note: By default, responsive resizing is not included in the
gulp serve
command, as it can be very computationally expensive. This can be enabled by uncommenting['responsive']
in theimages
andimages:optimized
tasks.Note: By default, generated images and
/_data/responsiveMetadata.json
are included in the.gitignore
.
If you want to use this repo for your next project, make sure to make the following changes:
- Edit
_config.yml
, filling in the HTML metadata associated with your site. - Edit
package.json
providing aname
,version
,description
,license
, andrepository.url
. - Remove the
.git
folder, so that you start from a fresh commit history. - Edit
LICENSE.md
andREADME.md
to your preference.
An overview of Gulp commands available:
Builds the site into the dist
directory. This includes:
- SCSS w/ linting, sourcemaps and autoprefixing
- JS linting and uglification
- Image optimization and resizing
This is used for distributing an optimized version of the site (for deployment). It includes everything from gulp build
as well as:
- SCSS minification
- CSS / JS inline-sourcing
- more rigorous image optimization
Resizes images in the _img/res/raw
directory into _img/res/<size>
directories, for several different heights in pixels (default: 20, 200, 800, 1600).
Watchs for changes in local files and rebuilds parts of the site as necessary, into the dist
directory.
Runs gulp watch
in the background, and serves the dist
directory at localhost:3000
with automatic reloading using Browsersync.
├── _img/ # All images that will be hosted statically.
└── res/ # Responsive images
├── 20/ # 20px tall images
├── 200/ # 200px tall images
├── ... # ...
└── raw/ # Full size images
├── _includes/ # Jekyll HTML includes
├── _js/ # JavaScript libraries and scripts, pre-compilation
├── _layouts/ # Jekyll HTML layouts
├── _posts/ # Jekyll HTML/Markdown posts
├── _scss/ # Stylesheets, pre-compliation
├── _site/ # GENERATED Jekyll builds the site into this directory
├── css/ # GENERATED Gulp builds SCSS into this directory
├── js/ # GENERATED Gulp builds JS into this directory
├── img/ # GENERATED Gulp builds images into this directory
├── node_modules/ # GENERATED NPM installs JS modules here.
├── _config.yml # Metadata associated with the site.
├── Gulpfile.js # Controls Gulp, used for building the website
├── index.html # The root HTML file for the website
├── LICENSE.md # This project's license
├── package.json # Dependencies
└── README.md # This file