metalsmith-gulp-boilerplate

A starter template for Metalsmith + Gulp + Jest projects.

Installation

Make your project folder and clone metalsmith-boilerplate into it

$ mkdir new-metalsmith-project
$ git clone https://github.com/radiovisual/metalsmith-gulp-boilerplate.git new-metalsmith-project

Run the following command within your new project directory:
```
$ npm install
```
Assuming you have installed Gulp globally, start the build/watch process with this command:
```
$ gulp
```
If this is your first build, you might want to package your javascript dependencies with this command:
```
$ gulp build-deps
```
This will gather all the js files in your js/vendor/ directory and package them into js/bin/dependencies.min.js. Use this command each time you add a new dependency to js/vendor.
Now you are ready to start Metalsmithing! 👍

Usage Notes

General

This boilerplate represents an opinionated setup for building static websites with Metalsmith and Gulp. It assumes you want to use Browserify with your custom scripts and helps you wrap all your javascript dependencies into one file. It uses the Sass precomplier and Handlebars templates. Gulp is responsible for the live-reloading (via BrowserSync) and the CSS / Browserify steps. Metalsmith is responsible for compiling/generating the site files.

Configuration

Use the site.json file to change or update the default configuration settings. The current defaults contain your source path, destination path, filenames to assign generated files, globs for gulp, and general site metadata. If you want to change the gulp or metalsmith builds, use the gulpfile.js or metalsmith.js files.

Packaging Javascript Dependencies

When you have added new dependencies to your js/vendor directory, package the dependencies with this command:

$ gulp build-deps

By default, this will concatenate and minify all your dependencies to this file: js/bin/dependencies.min.js, but you can override the file name and location in the sites.json file. If you do not use this command, then you will need to import your dependencies into your templates manually. This build step is not automatic, because it is unnecessary to bundle your dependencies on every gulp/metalsmith build if your dependencies only change rarely.

Importing Files into Your Templates

By default, your generated files are available in Handlebars like so:

<!-- your generated css -->
<link rel="stylesheet" href="{{rootPath}}css/styles.min.css">

<!-- your generated js dependencies -->
<script src="{{rootPath}}js/bin/dependencies.min.js"></script>

<!-- your browserified scripts -->
<script src="{{rootPath}}js/bin/bundle.min.js"></script>

Features and Defaults

These are the current defaults, but you can swap these out for anything you want.

Templating: Handlebars via metalsmith-layouts
Easy Template Helper Integration: Any node modules dropped into layouts/helpers will automatically be available to your Handlebars templates
CSS Precompiler: SASS
Live Reloading: BrowserSync
Relative Navigation: Solved with metalsmith-rootpath
Browserify: Browserify your javascript source automatically
Dependency Wrapping: Minify and concat all your dependencies into one file
Unit Testing: via Jest

What Next?

Add some Metalsmith plugins to customize your Metalsmith build.
Add some Gulp plugins to customize your gulp build.

License

To the extent possible under law, Michael Wuergler has waived all copyright and related or neighboring rights to this work.

welt/metalsmith-gulp-boilerplate