Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/radiovisual/metalsmith-gulp-boilerplate
A starter template for Metalsmith + Gulp + Jest projects
https://github.com/radiovisual/metalsmith-gulp-boilerplate
browserify gulp handlebars jest metalsmith metalsmith-boilerplate metalsmith-gulp
Last synced: 2 months ago
JSON representation
A starter template for Metalsmith + Gulp + Jest projects
- Host: GitHub
- URL: https://github.com/radiovisual/metalsmith-gulp-boilerplate
- Owner: radiovisual
- License: cc0-1.0
- Created: 2015-08-17T11:09:40.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2018-12-14T16:23:14.000Z (about 6 years ago)
- Last Synced: 2023-04-26T07:42:42.328Z (almost 2 years ago)
- Topics: browserify, gulp, handlebars, jest, metalsmith, metalsmith-boilerplate, metalsmith-gulp
- Language: JavaScript
- Homepage:
- Size: 80.1 KB
- Stars: 12
- Watchers: 3
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# metalsmith-gulp-boilerplate [](https://travis-ci.org/radiovisual/metalsmith-gulp-boilerplate)
> A starter template for [Metalsmith](https://github.com/segmentio/metalsmith) + [Gulp](https://github.com/gulpjs/gulp) + [Jest](https://github.com/facebook/jest) projects.
## Installation
1. 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
```
2. Run the following command within your new project directory:
```
$ npm install
```
3. Assuming you have [installed Gulp globally](https://github.com/gulpjs/gulp/blob/master/docs/getting-started.md#1-install-gulp-globally),
start the build/watch process with this command:
```
$ gulp
```
4. 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`.
5. *Now you are ready to start Metalsmithing!* :thumbsup:
## Usage Notes
#### General
This boilerplate represents an opinionated setup for building static websites with Metalsmith and Gulp. It assumes
you want to use [Browserify](http://browserify.org/) with your custom scripts and helps you wrap all your javascript
dependencies into one file. It uses the [Sass](http://sass-lang.com/) precomplier and [Handlebars](http://handlebarsjs.com/)
templates. Gulp is responsible for the live-reloading (via [BrowserSync](http://www.browsersync.io/)) 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:
```html
```
## Features and Defaults
These are the current defaults, but you can swap these out for anything you want.
- **Templating:** [Handlebars](http://handlebarsjs.com/) *via [metalsmith-layouts](https://github.com/superwolff/metalsmith-layouts)*
- **Easy Template Helper Integration**: Any node modules dropped into `layouts/helpers` will automatically be available to your Handlebars templates
- **CSS Precompiler:** [SASS](https://github.com/stevenschobert/metalsmith-sass)
- **Live Reloading:** [BrowserSync](https://github.com/mdvorscak/metalsmith-browser-sync)
- **Relative Navigation:** Solved with [metalsmith-rootpath](https://github.com/radiovisual/metalsmith-rootpath)
- **Browserify:** [Browserify](http://browserify.org/) your javascript source automatically
- **Dependency Wrapping:** Minify and concat all your dependencies into one file
- **Unit Testing:** via [Jest](https://github.com/facebook/jest)
## What Next?
- Add some [Metalsmith plugins](http://www.metalsmith.io/#the-plugins) to customize your Metalsmith build.
- Add some [Gulp plugins](http://gulpjs.com/plugins/) to customize your gulp build.
## License
[](http://creativecommons.org/publicdomain/zero/1.0/)
To the extent possible under law, [Michael Wuergler](http://www.numetriclabs.com) has waived all copyright and related or neighboring rights to this work.