A customizable Gulp 4 template

for static sites

DEPRECATION: This template should work, but is not fully up-to-date, which is why I've moved on and built a new template over at webpack-static-site-template. The front-end technologies are pretty much the same (Nunjucks, SCSS, Typescript), but the build tool is now just Webpack, which helps with the speed and maintainability, as this one combined Gulp and Webpack in what I considered to be a rather dirty approach.

---

Features

• HTML: Nunjucks template engine. Renders at build time for static websites. Includes a basic template templates/base.njk to get you started and minification on production builds.
• CSS: SCSS (and SASS) support. Includes minification on production builds and autoprefixing via Autoprefixer.
• JS: TypeScript support (via webpack and Babel). Multiple entry points are supported (e.g. a script for each page; see tasks/configuration.ts).
• IMAGES and ASSETS: Automatically copy your images and other assets into your build.
• DEVELOPMENT: Browsersync support (real-time browser updates when you're developing).
• LINTING: eslint for TypeScript, stylelint for SCSS with configuration files set up and relevant scripts prepared.
• Easy customization via options in tasks/configuration.ts and modular tasks in tasks

---

1. Installation

To get started fork, clone or download the repository.

Cloning or downloading

In order to clone this repository, run the command below or use the download button.

git clone https://github.com/DefaultSimon/gulp-nunjucks-sass-template.git

If you intend to push changes to your site to your own repository though, you'll have to update the remote in your clone (which forking already does for you). For further help, see this article.

Forking

Forking makes an online copy of this repository which is then available under your repositories. Click the Fork button or see help here.

2. Usage

This projects uses Yarn 2 as the package manager. Install if needed and run yarn install in the base directory, and you're done.

Familiarize yourself with the template by looking at the documentation and the relevant files. When you've looked around a bit feel free to, if needs arise, start to customize tasks/configuration.ts and even the individual tasks.

2.1. Structure

The file structure is as follows:

src
- pages
  > your Nunjucks pages (.njk) here
  > the pages will be compiled to HTML and copied to "dist"

- templates
  > Nunjucks templates here (already includes one: base.njk)
  > See index.njk for an example on extending templates
  
- scss
  > SCSS files (main.scss is the entry point and should import other files)
  > normalize.css, pure.css, include-media and Bones are available.

- scripts
  > This project supports multiple entry points!
  > see tasks/configuration.ts to see an example on how to set them up

- images
  > images are copied into "dist/assets/images"

- other
  > *any* files are recursively copied to the "dist/assets" directory
  > for cases where you want some custom assets in your build

2.2. Nunjucks (HTML)

Nunjucks is a powerful HTML templating engine built by Mozilla. The syntax is similar to (and inspired by) Python's jinja2. For more on templating, read Nunjucks' documentation.

Put your pages in src/pages and your templates in src/templates. In this project, a base template named base.njk is already set up. A few examples on using Nunjucks are available in src/pages.

To add custom Nunjucks globals and filters, check out tasks/configuration.ts. The tags global is automatically filled with useful values, read more below.

2.3. SCSS (CSS)

SCSS is a stylesheet language that compiles to CSS. This project uses the Dart Sass compiler.

By default, there is a single entry point in src/scss/main.scss that imports a variety of rules and modules.

This project's template includes the following:

• normalize.css for a consistent base across browsers
• pure.css as a style foundation
• include-media (Sass library for @media queries) - a handy tool for handling @media queries in SCSS. Breakpoints are customized with help from a bunch of articles and frameworks and packed into the modules/_media.scss module with shorthands for easy styling.
• Bones, a personal set of common rules compacted into mixins and CSS classes. Short documentation is available in bones.njk/bones.html and the source is available at src/scss/vendor/bones.
• A variety of basic sizing, animation-related and other mixins, available in src/scss/modules.
• rem units scaled to 10px (62.5%, adjusted in src/scss/base/_defaults.scss).

The larger modules are located in src/scss/vendor and can be easily removed if you do not need them by deleting the relevant directory and removing the import in main.scss.

The resulting CSS <link> tag to the styles is available in the variable tags.css.

{{ tags.css | safe }}

This will output <link href="assets/css/style.min.css" rel="stylesheet">. The safe filter is required as Nunjucks would otherwise escape HTML content.

2.4. TypeScript

TypeScript is an open-source language which builds on JavaScript by adding static type definitions.

All *.ts code in src/scripts goes through webpack and Babel (with preset-env and preset-typescript). To facilitate splitting your code, multiple entry points ("multiple scripts") can be set up in tasks/configuration.ts.

The resulting <script> tags (one for each entry point) will be available under tags.scripts.

For example: with an entry point named index, you can use the following variable in your page:

{{ tags.scripts.index | safe }}

This will output <script src="assets/js/index.js"></script>. The safe filter is required as Nunjucks would otherwise escape HTML content.

Another useful feature: importing SCSS variables into your TypeScript is easy! Webpack is already configured, simply import the .scss file, and you're done (see src/scripts/index.ts for an example)! This will not impact the styles (no additional file is emitted), but will import the variables you might want to use. Side note: instead of a relative path, the @SCSS alias is available (as shown in the example).

2.5. Development

To start developing, execute yarn run dev in the console. This will build a development version of the project, open the browser and watch for changes, updating them in real-time in the browser.

To just build in production mode (enabling minified scripts, webpack's production mode and such), execute yarn run buildProduction (or buildDev for a one-time dev build). For other single tasks, check out tasks/index.ts.

2.6. Linting

Linting will check your code against a set of TypeScript and SCSS rules. The rules can be adjusted in .eslintrc.js and .stylelintrc.json.

To use linters, prefferably enable support for ESLint and Stylelint in your IDE, or run the following scripts to lint manually:

• lintTS (or lintTSFix to automatically fix problems)
• lintSCSS (or lintSCSSFix to automatically fix problems)

For example, run yarn run lintTSFix to run the lintTSFix script.