- Gulp 4 (alpha) with an ES6 Babel gulpfile
- Config file for paths
gulp-config.js - Uses Yarn instead of Bower+NPM
- Uses
gulp-includedirectives to bundle all scripts - Relies on binaries from the local project's
./node_modules/bininstead of globals (except Yarn)
These starter files can be used to generate a prototype or flat-file website. The Nunjucks template language is used for the HTML due to its close relationship to Twig.
After using this starter kit to build flat HTML prototypes, the Nunjucks files can then be re-used as a starter point for Twig-based templates such as Wordpress with Timber or Craft CMS, and any platforms which can use Nunjucks or Jinja.
- NodeJS LTS+
- Yarn
- MacOS:
brew install yarn - Windows: Get Installer
- Linux: Instructions
- MacOS:
- Gulp4
- Fork and clone repository or download the ZIP file
- From the terminal inside the project folder, run
yarn - Run
gulpto build and watch for changes- Launches web server with BrowserSync at http://localhost:3000
- Nunjucks template language (nearly equivalent to Twig), compiles to flat HTML
- Extend/Include templates, Variables, If/Else logic and more
- Starter template based on HTML5 Boilerplate
- Sass for writing CSS
- Processes through Autoprefixer (last 2 browser versions)
- Includes normalize.scss library
- Includes modularscale-sass library
- Includes base styles and common global variables
- Includes sourcemaps to trace errors to the source Sass files
- Automatically includes and concatenates using
gulp-include- jQuery included by default
- IE Object Fit polyfill included
- Console log error prevention script included
JavaScript files are included using //=require or //=include directives within the script file:
//=require plugins/prevent-console-errors.js
//=require ../../../node_modules/jquery/dist/jquery.js- Compresses JS files with Uglify
- No linter—add your own if needed
- Sourcemaps is available but not configured for JavaScript
- Images placed in
./src/assets/images/are optimized by default with imagemin- Place directly in
./dist/assets/images/if optimization is not needed or undesired
- Place directly in
The best way to template with Nunjucks, a Twig-like template language, is to extend from a base template. Base templates or partials should be prefixed with an underscore _ to prevent them from compiling into their own standalone templates. For example:
Base Template (Simplified): _base.njk
<!DOCTYPE html>
<html>
<head><title>{{ title }}</title></head>
<body>
{% block content %}
<p>Fallback content</p>
{% endblock content %}
</body>
</html>Extended Template: index.njk
{% extends "_base.njk" %}
{% set title = "Hello World" %}
{% block content %}
<h1>Hello World!</h1>
<p>You've reached my site!</p>
{% endblock content %}Outputs (Simplified): index.html
<!DOCTYPE html>
<html>
<head><title>Hello World</title></head>
<body>
<h1>Hello World!</h1>
<p>You've reached my site!</p>
</body>
</html>You can also include partials with a simple include line:
<header>
{% include "_partials/_hero-slider.njk" %}
</header>For more advanced techniques, check out the Nunjucks templating documentation.
By default, the following setup is used:
- Working and Production directories (change in
gulp-config.js)src- Working directorydist- Production directory- This directory and its subfolders will not be created until the first
gulpbuild command
- This directory and its subfolders will not be created until the first
assets- Assets directory for images, CSS, scriptstemplates- Templates directory for Nunjucks files
- Gulp
gulpcommand for default build with BrowserSync preview, also starts watching files- Launches web server with BrowserSync at http://localhost:3000
gulp watchcommand to watch files for changes
- HTML/Nunjucks
- Build templates in
./src/templates/using either the.njk,.nunjucks,.njk.htmlor.htmlextension - Name partials and base extends with a leading underscore
_ - Builds to
./dist/
- Build templates in
- CSS/SASS
- Write SCSS or SASS in
./src/assets/sass/main.scss- Import all partials in herebase/- Base styles
- Name partials with a leading underscore
_ - Concatenates to
./dist/assets/css/main.css - Note: Use
yarn add <module> --devto maintain SASS libraries and link to them directly- Example:
@import '../../../node_modules/modularscale-sass/stylesheets/modularscale';
- Example:
- Write SCSS or SASS in
- JS
- User script file in
./src/assets/js/scripts.jsuses gulp-include directives to set bundle order of additional scripts - Place additional scripts in
plugins/ - Note: Use
yarn add <module> --devto maintain JS libraries and link to them directly- Example:
//=require ../../../node_modules/jquery/dist/jquery.js
- Example:
- User script file in
- Images
- Place images for processing in
./src/assets/images/ - Runs imagemin default optimization (change in
gulpfile.babel.js) - Outputs to
./dist/assets/images/
- Place images for processing in
./
└ dist/ # distribution folder
└ assets
└ css/
└ main.css # main CSS file
└ images/
└ js/
└ scripts.js # bundled scripts
└ src/ # working folder
└ assets
└ images/ # images to be optimized
└ js/
└ scripts.js # use this for custom scripts
└ plugins/ # use for non-package.json scripts
└ scss/
└ main.scss # use this to include partials
└ base/
└ _breakpoint-query.scss
└ _buttons.scss
└ _normalize.scss
└ _scaffolding.scss
└ _typography.scss
└ _variables.scss
└ templates/ # use for HTML/Nunjucks templates
└ _base.njk # base template
└ index.njk # index.html, extends _base.njk
Use the following commands to add modules or libraries to package.json. When you clone the repo to a new directory or machine, just run the yarn add command. Yarn uses the same repositories as npm, and locks the version.
- New project modules/libraries can be added with
yarn add <package-name> - New build modules/libraries (such as gulp plugins) can be added with
yarn add <package-name> --dev - If you want to shift all packages to their latest versions, you can do
yarn upgrade. Do not do this unless you know what you are doing, as it could break your project.
Inspired by:
Released under an MIT license.