These starter files can be used to quickly develop a prototype or flat-file website. The Pug template language is used for the HTML due to its terse structure and integration of JavaScript, and Sass is used for its flexibility and extended capabilities.
- Pug template language (formerly Jade) with a nice terse syntax
- Sass for writing quick CSS
- jQuery 3.6 included
- PostCSS with the Autoprefixer and CSSNano extensions
- Gulp 4 with a Babel gulpfile for ES6 syntax
- Uses Yarn for Node package management
- Relies on local
node_modulesinstead of globals (except Yarn)
- NodeJS LTS+
- Yarn
- MacOS:
brew install yarn - Windows: Get Installer
- Linux: Instructions
- MacOS:
- Gulp 4
- (Optional) All platforms:
yarn global add gulp-clito build withgulp
- (Optional) All platforms:
- Fork and/or clone the repository or download the ZIP file
git clone https://github.com/josh-clarke/pug-web-starter-files
- From the terminal inside the project folder, run
yarnto install node modules - Run
yarn build(orgulpif you havegulp-cliinstalled globally) to build and watch for changes- Launches web server with Browsersync at http://localhost:3000
- Pug template language (formerly Jade)
- Extend/Include templates, Scripting, Mixins, Interpolation and more
- Starter template based on HTML5 Boilerplate
- Sass for writing CSS
- Uses the official Dart Sass transcription engine
- Processes through PostCSS with the Autoprefixer and CSSNano extensions
- Uses the Browserslist config in
package.jsonfor Autoprefixer (usesdefaultandnot IE 11)
- Uses the Browserslist config in
- Includes normalize.scss library
- Includes modularscale-sass library
- Includes simple base styles and common global Sass 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
- Uses
gulp-includedirectives to bundle all scripts into one (see below) - Console log error prevention script included
- Includes sourcemaps to trace errors to the source JS files
JavaScript files can be included into other files 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
- Sourcemaps is available but not configured for JavaScript
- No linter; add your own if needed
- Images placed in
./src/assets/images/are optimized by default with gulp-imagemin- Place directly in
./dist/assets/images/if optimization is not needed or undesired
- Place directly in
The best way to template with Pug, a HAML-like template language, is to extend from a base template. Base templates or partials may be prefixed with an underscore _ to prevent them from compiling into their own standalone templates. For example:
Base Template (Simplified): _base.pug
doctype html
html
block vars
- var title = 'Fallback Title'
head
title #{title}
body
block content
p Fallback content.Extended Template: index.pug
extends _base.pug
block vars
- var title = 'Hello World'
block content
h1 Hello World!
p You've reached my site!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 like this:
header
include _partials/_hero-slider.pugFor more information, check out the Pug templating documentation.
By default, the following setup is used:
- Working and Production directories (change in
gulp-config.js)src- Working directorydist- Production directory (appears after first build)- 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 Pug files
- Gulp
yarn buildor optionalgulpcommand for default build with BrowserSync preview and watch files for changes- Launches web server with BrowserSync at http://localhost:3000
- Pug Templates
- Build templates in
./src/templates/using either the.pug, or.jadeextension - Name partials and base extends with a leading underscore
_ - Builds to
./dist/
- Build templates in
- CSS/Sass
- Write Sass in
./src/assets/sass/main.scss- Import all sass 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 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 (appears after first build)
└ 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 Pug templates
└ _base.pug # base template
└ index.pug # index.html, extends _base.pug
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.
- 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.
Based on:
Inspired by:
- https://github.com/jh3y/gulp-boilerplate
- https://github.com/gjhead/Starter-Files-Grunt
- https://github.com/gjhead/Starter-Files-Gulp4
License
Released under an MIT license.