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".
This project depends on Hugo and Node being installed on your machine. To initiate a new site, do:
git clone https://github.com/felics/blaupause project
cd project
npm install
or yarn install
gulp
Developer Mode
with Sourcemaps
and debugging helpersProduction Mode
for optimized buildslayout
-boilerplate[1] Due to the structure of this repository, Hugo Themes are not supported.
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
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 changehugo.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.
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.
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>
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
.
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./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).