About

juckWonder - Nunjucks starter kit (static site generator)

A starter kit to build websites using Nunjucks a rich and powerful templating language for JavaScript.

  • 🐛 Framework free
  • 🐙 CMS free
  • 🐝 Minimal CSS
  • 🐬 Block based templating
  • 🌈 Optimised for accessibility, speed and search engines, - Lighthouse report

Requirements

Prerequisite How to check How to install
Node.js >= 10.0 node -v nodejs.org
gulp >= 4.0.0 gulp -v npm install -g gulp

Installation

Install Node dependencies (Gulp 4.0.2, Nunjucks and a few others)

npm install gulp --save-dev

Edit gulpfile.js for varibales such as folder names


Build process

gulp dev for development gulp build for production (builds to /docs) cd docs && npx serve to see built files locally


Localhost

cd docs && npx serve


Testing

Uses cypress.io and test are located in cypress/integration/tests

./node_modules/.bin/cypress open

or via the command line

$(npm bin)/cypress run

or via npm via this method

GUI:

npm run test

Command line:

npm run testCmd


Deployment

This has been set up for deploying tpo GitHub pages but it's static so there are many options


Dependencies

This uses a few libraries and open-source plugins, all MIT licensed. Apart from maybe the cookie notice (local law permitting) none are essential and can be removed.

NOTE: this site uses Plausible.io for analytics (which doesn't place a cookie on the user's machine) so the cookie JS is not being used in this build (although it's commented out if you wish to see how this might work)


VSCode

Based on improvements from this CSS Tricks article

  • Creation of workspace file juckWonder.code-workspace
  • Custom Workspace icon - +i then paste image
  • Launch terminal commands when opening a project .vscode/tasks.json e.g. gulp dev run once in Terminal >> Run task
  • Exclude .css files from global search in .vscode/settings.json:
    "search.exclude": {
    "**/*.css": true
    }

Google sheets (experimental)

npm run build-sheets

or

ruby update_data.rb

or

gulp data

Uses a google spreadsheet to manage site data, this is pulled down via gulp data (part of the build process). A ruby script update_data.rb is used to transform the CSV into JSON files

Site data set global = data.site[0]

In files global.socialImage

Gallery images for gallery in data.gallery


Customisation

There are some site variables that should be edited away from the boilerplate defaults

  • Change site vars - data.json
  • Site name - /images/fav/manifest.json
  • Update social images in /images/og, /images/fav/, logotype.svg
  • Update form endpoint in contact.html - currently using Formspree
  • Add your own analytics in _analytics.njk
  • There is a little service worker in sw.njk.js that caches the main files and serves them up if there is no network access

Page variables

Meta description (this also changes the twitter and facebook share text)

shortDesc = "Blah blah blah"

Body class - set bodyClass = "jw-gallery" Page title - set pageTitle = "Gallery"

Custom Macros

I've created a bunch of custom macros (reusable chunks of content - see Nunjucks guide)

  • Hero block - hero.njk
  • Text block - text.njk
  • Text block (with some extra padding) - float.njk
  • Full width image block - image.njk
  • Call to action block - cta.njk
  • Map block - map.njk
  • Modal block - modal.njk

These macros will take a series of parameters, for example image path, title, link to mardown file, classname etc. See src/index.html for examples and syntax order

Hero macro - hero('path/to/image.jpg', 'path/to/image-large.jpg', 'Block title', 'Block content', 'class')

Text macro - text('#backgroundcolor', 'alignment', '#blockcolor', 'path/to/image.jpg', 'path/to/image-large.jpg', 'Block title', 'markdown.md', 'class')

Social macro (used in the footer) - social('instagram', 'twitter', 'github', 'email', 'phone')


License

juckWonder is licensed under MIT license.