blaupause

Blaupause is a developer-friendly Hugo starter kit based around gulp-tasks. It comes es6-ready with several helpers for SVG, fonts and a basic structure for the html, scss and javascript. For a detailed listing of what is included, see "In the box".

Installation

This project depends on Hugo and Node being installed on your machine. To initiate a new site, do:

1. git clone https://github.com/felics/blaupause project
2. cd project
3. npm install or yarn install
4. gulp

In the box

• Gulp-based, automatic builds
• BrowserSync live-reloading environment
• Developer Mode with Sourcemaps and debugging helpers
• Production Mode for optimized builds

JS

• Webpack
• Babel
• ESLint
• Unit tests via Jest
• Customizable Modernizr

SCSS

• SASS
• Autoprefixer
• Stylelint
• Minimal SASS boilerplate based on SASS Guidelines, Sanitize.css and a couple of useful mixins

Static Site Generator

• Hugo[1] with a minimal layout-boilerplate

Images/SVG

• svg-sprite to generate SVG symbol sprites
• imagemin

Dev Tools

• EditorConfig
• Travis-based tests
• (Example) Automatic Travis deployment to Github Pages

[1] Due to the structure of this repository, Hugo Themes are not supported.

Tasks & Configuration

Basic Configuration

The build configuration is setup in ./internals/gulp/config.js and ./hugo/config.yaml.

# ./hugo/config.yaml

# The baseurl of the build artifact. Ignored in development mode
baseurl: "http://fspoettel.github.io/blaupause/"

# Params
# Blaupause configuration can be found under the key `blaupause`
params:
  blaupause:
    # Includes our custom modernizr built with gulp if set
    useModernizr: false

# The rest of the file is a "normal" Hugo config. Check the hugo docs to see how it works if you are not familiar with it

// ./internals/gulp/config.js

/**
 * Sets the target path for the build
 * @type {String}
 */
const destinationPath = 'public';

/**
 * Sets the target path for static assets (scripts, styles, images, svg)
 * @type {String}
 */
const assetPath = `${destinationPath}/static`;

/**
 * Source path of the site template
 * @type {String}
 */
const sourcePath = 'src';

/**
 * Host that BrowserSync serves from
 * @type {String}
 */
const host = 'localhost';

/**
 * Port that BrowserSync serves from
 * @type {Number}
 */
const port = process.env.PORT || 3000;

// The rest of the file contains task-specific configuration that can be tailored to your use-case

Tasks & Task Configuration

gulp

Runs gulp build and starts a BrowserSync instance. Whenever you change a source file, the BrowserSync instance will reload your connected browsers with the changes.

gulp build

Builds all content and assets from src to public.

gulp build:clean

Removes the public-folder (executed automatically on gulp build).

gulp copy:build

Copies a set of files files into the public-folder. By default, it will copy any stray files from the root directory of src to the root of public. The task can be extended with custom directives in the gulp config.

gulp hugo:build

The Hugo documentation can be found here and covers pretty much anything you need to know about the static site generator. The Hugo content and configuration reside in ./hugo; the layouts in ./src/layouts. Hugo Themes are currently not supported.

In Development Mode, the baseUrl is replaced with the URL used by BrowserSync. To generate a production-ready build with correct URLs, run gulp build -p or gulp hugo:build -p (see below).

Make sure to adjust layoutdir in ./hugo/config.yaml if you decide to change hugo.sourcePath in the gulp config.

gulp images:build

Optimizes and copies images in ./src/images to public. The imagemin-settings and file-endings imagemin scans for can be configured in the gulp config.

gulp images:clean

Removes the files generated by the images-task.

gulp modernizr:build

Generates a custom Modernizr build with Customizr. The task can be configured in the gulp config.

gulp modernizr:clean

Removes the Modernizr build created by the modernizr-task.

gulp scripts:build

Transpiles and bundles js-files in ./src/scripts/*.js via Webpack and Babel. Can be configured in the gulp config.

gulp scripts:clean

Removes the script bundles created by the scripts-task.

gulp styles:build

Compiles the scss-stylesheets in ./src/styles/*.scss and automatically adds prefixes via autoprefixer. You can specify the version ranges targeted by Autoprefixer in the gulp config. You can add PostCSS plugins in ./internals/gulp/tasks/styles.js.

gulp styles:clean

Removes the stylesheets created by the styles-task.

gulp svg:build

Bundles all .svg-files in ./src/images and compiles them into a symbol sprite. You can easily reference the generated sprites via the image/svg Hugo partial (see below).

gulp svg:clean

Removes the svg sprite created by the svg-task.

Production Builds

You can generate a production-ready build ("real" BaseURL, no drafts, no sourcemaps, NODE_ENV = "production" for JS builds, uglified code) by passing -p to any build task.

Hugo Partials

image/svg

Reference a SVG-symbol from /static/svg/sprite.symbol.svg# by ID. SVGs are generated by gulp svg:build in the default build.

  <div class="icon">{{ partial "image/svg" (dict "id" "the-icon" "class" "optional-class") }}</div>

Adding tasks

You can add tasks by creating a .js-file in .internals/gulp/tasks that contains a task, a reference to gulp and the gulp-modules you want to use. You can then add it to the run-sequence in build.

Deploy

The build product can be deployed practically anywhere since it is just a static html page. This repository serves as an example on how to deploy to gh-pages.

• ./hugo/config.yaml{baseurl} is set to the real path of the site
• Travis is set up to automatically run ./internals/scripts/deploy.sh after a successful build of the docs-branch. deploy.sh runs gulp build -p and force-pushes the build-folder to the gh-pages-branch (for more information on how to set up Travis-deployment to gh-pages, check out steveklabnik/automatically_update_github_pages_with_travis_example).

minimal-mistakes_hugo-port

A Hugo port of the Jekyll theme Minimal Mistakes