Yeogurt Generator

A generator for creating static sites. Helps you harness the power of your favorite tools: Jade, Nunjucks, Gulp, and much more!

NOTE: If you want to create an Application using React, React Router, and Baobab, be sure to check out generator-neopolitan

Features
Getting Started
Setup
Gulp Workflow
Sub-Generators
Guides
Common Issues
Roadmap
Contributing
Testing Generator
Release History
License

Features

Included in every project

Preview server with Browsersync
Automated build process that includes: compilation of preprocessors (Jade, Sass, etc), minification of CSS and HTML, compression of Javascript, and optimization of images
.editorconfig for consistent coding styles within text editors
Sourcemaps for JavaScript and Stylesheets
JavaScript Linting with ESLint
ES6/2015 support out of the box using Browserify with Babel

Available Options

Project/Site naming
Less, Sass (via node-sass), or Stylus for Stylesheets
Jasmine or Mocha + Chai for JavaScript unit testing
Karma for running unit tests
Jade or Nunjucks for templating

Getting Started

This generator utilizes Yeoman and Gulp to scaffold out projects, automate tasks, and manage front-end dependencies respectively. If this is your first time here, it is recommended you read about these tools before proceeding.

Installation

There are a few dependencies that this project relies on:

NOTE: For OSX users You may have some issues compiling code during installation of packages. Please install Xcode from App Store first. After Xcode is installed, open Xcode and go to Preferences -> Download -> Command Line Tools -> Install to install command line tools.

Node.js

Check to see if you already have Node installed. Do this by bringing up a terminal/command prompt and type node -v. If the response shows a version at or above v0.12.x, you are all set and can proceed to installing Yeoman, Gulp, and Bower. If you see an error and/or your version is too low, navigate to the Node.js website and install Node from there.

Yeoman & Gulp

Once you have Node installed, make sure you have these tools by opening up a terminal/command prompt and entering following commands:

Command	Response
`yo -v`	at or above `v1.2.1`
`gulp -v`	`gulp-cli` at or above `v0.3.9`

If you get any errors and/or you're version(s) are too low, you should run npm install -g yo gulp. This will install both tools and update them to their latest versions.

Yeogurt

Now that you have all the needed dependencies, you can install this generator with the following command: npm install -g generator-yeogurt

That completes installation! So at this point you should have all the needed tools to start working Yeogurt.

Setup

When starting a new project, you will want to: open up a terminal/command prompt, make a new directory, and navigate into it.

mkdir my-new-project && cd $_

then, run the Yeogurt generator.

yo yeogurt

Optionally, you can skip the automated installation of npm packages by passing in --skip-install. The main reason to use this is if you have spotty/no internet connection, but would still like to generate your project.

yo yeogurt --skip-install

Follow all the prompts and choose what suits you most for the project you would like to create. When you finish with all of the prompts, your project scaffold will be created and all dependencies will be installed.

NOTE: If you used the --skip-install option, no dependencies will have been installed and your gulp tasks will NOT work. You will need to run npm install in your project's root directory in order to get started running automated tasks

Once everything is installed, you will see a project structure like below:

├── build/                     # Folder for production build output
├── tmp/                       # Folder for temporary development output
├── src
|   ├── _data                  # JSON files that add data to templates (Example, will not be generated)
|   ├── _images                # Images
|   ├── _layouts               # Layout structure for app
|   |   └── base.jade
|   ├── _modules               # Reusable modules
|   |   └── navbar             # Example module (will not be generated)
|   |       ├── __tests__
|   |       |   └── navbar.spec.js
|   |       ├── navbar.jade
|   |       ├── navbar.js
|   |       └── navbar.scss
|   ├── _styles               # Global styles, mixins, variables, etc
|   |   └── main.scss         # Main stylesheet (import everything to this file)
|   ├── _scripts              # Global scripts, base classes, etc
|   |   └── main.js           # Main bootstrap file
|   ├── fonts                 # Fonts (Example, will not be generated)
|   ├── index.jade            # Homepage template
|   ├── favicon.ico
|   └── robots.txt
├── gulpfile.babel.js         # Gulp task configuration (using ES6)
└── package.json              # Dependencies and site/folder configuration

Congratulations! You should now have successfully created a Yeogurt project and are ready to start building out your site/app.

Now you can run the following gulp tasks:

gulp serve for previewing your site/app on a development server.
gulp serve --production for previewing a production version of your site/app.
gulp for testing and building a development version of your site.
gulp --production same as gulp but builds a production version of your site.
gulp test for linting your scripts and running unit tests.

You can learn more about what tasks are available in the gulp tasks section.

Configuration

In the package.json file, within the root of the generated project, you have the ability to configure some project settings:

Site

Setting	Description
host	Host URL of the development server (browserSync)
port	Port of the development server (browserSync)
baseUrl	Root directory of your site

Main Directories

Setting	Description
source	Source folder for all development files (default location for page subgenerator)
destination	Build folder where production version of site is generated
temporary	Temporary folder where development server files are generated

Source Directories

Folders relative to the source configured directory

Setting	Description
data	Data folder where JSON files are loaded into templates
scripts	Scripts folder where all `.js` files are located (main.js must be in root of this folder)
styles	Styles folder where all stylesheet files are located (main stylesheet must be in root of this folder)
modules	Modules folder where all reusable code should live (default location for module subgenerator)
layouts	Layouts folder where all layout templates should live (default location for layout subgenerator)
images	Images folder where all `.png, jpeg, jpg, svg, gif` files should live

Default configuration:

"//": "CUSTOM CONFIGURATION",
"config": {
  "//": "Local Server Settings",
  "host": "127.0.0.1",
  "port": "9010",
  "baseUrl": "/",
  "//": "Gulp Task Directories",
  "//": "NOTE: folders prefixed with an underscore (_) will have it removed when moved to build target (ex: src/_images -> build/images)",
  "//": "NOTE: folders NOT prefixed with underscore (_) will be copied to build target 1 to 1 (ex: src/fonts -> build/fonts)",
  "directories": {
    "source": "src",
    "destination": "build",
    "temporary": "tmp",
    "//": "Directories relative to `source` directory",
    "modules": "_modules",
    "layouts": "_layouts",
    "images": "_images",
    "styles": "_styles",
    "scripts": "_scripts",
    "data": "_data"
  }
}

Gulp Workflow

`gulp`

Runs gulp test and compiles/creates temporary server files

Extra Task Target(s)

Tasks	Description
`gulp --production`	Builds out an optimized site through compilation of preprocessors (Jade, Sass, etc), minification of CSS and HTML, uglification of Javascript, and optimization of images.

`gulp serve`

Starts up a development server that watches files and automatically reloads them to the browser when a change is detected.

Extra Task Target(s)

Tasks	Description
`gulp serve --production`	starts up a server that loads a production version of the site
`gulp serve --open`	starts up a server and opens it within your default browser

`gulp test`

Runs ESLint and Karma to lint and run JavaScript tests, respectively.

Extra Task Target(s)

Tasks	Description
`gulp test --watch`	runs `gulp test`, but also watches test files and auto runs tests when changes are detected.

NOTE: test:watch is only available if you chose to unit test your javascript

Note: Generators need to be run from the root directory of your app.

Default Generators

Note: (The following sub-generators can be used with any type of project)

Page

Creates a new page.

Example:

$ yo yeogurt:page contact

Produces:

src/contact/index.{jade,nunjucks}

Example #2: Specifying a layout

$ yo yeogurt:page contact --layout=one-col

Produces:

// Page that extends from 'src/_layouts/one-col'
src/contact/index.{jade,nunjucks}

NOTE: Pages will default to extending from src/_layouts/base if --layout is not provided

Module

Creates a new module.

Example:

$ yo yeogurt:module header

Produces:

src/_modules/header.{jade,nunjucks}
src/_modules/header.{scss,sass,less,styl}
src/_modules/header.js

Layout

Creates a new layout.

Example:

$ yo yeogurt:layout one-col

Produces:

src/_layouts/one-col.{jade,nunjucks}

Example #2: Specifying a layout

$ yo yeogurt:page contact --layout=one-col

Produces:

// Layout that extends from 'src/_layouts/one-col'
src/contact/index.{jade,nunjucks}

NOTE: Layouts will default to extending from 'src/_layouts/base'

Guides

Adding third-party libraries

Odds are that you will need to add some third party libraries to your project at some point. To do so, it is strongly recommended that you install them using NPM:

npm install [package name] --save

Once installed, you can access scripts within your JavaScript files like so:

import $ from 'jquery';

$(function() {
  console.log('Hello');
});

And you can access stylesheets by importing them to you chosen preprocessor like so:

Using SCSS:

// SCSS
@import 'node_modules/bootstrap-sass-official/scss/bootstrap';

// CSS
@import 'node_modules/normalize.css/normalize';

Using SASS:

// SASS
@import node_modules/bootstrap-sass-official/scss/bootstrap

// CSS
@import node_modules/normalize.css/normalize

Using LESS:

// LESS
@import 'node_modules/bootstrap/less/bootstrap';

// CSS
@import (inline) 'node_modules/normalize.css/normalize.css';

Using Stylus:

// Stylus
@import '../../node_modules/bootstrap-stylus/bootstrap';

// CSS import
@import '../../node_modules/normalize.css/normalize.css';

Data Files

If you want to load global data into your templates (jade or nunjucks), you can add JSON files in src/_data folder.

For example, add menu.json in src/_data folder:

{
  "name": "Home",
  "link": "/",
  "category": "Page",
  "status": "Development"
}

And it will be added to the site.data object so it can be used like so:

div
  h1= site.data.menu.name

Which outputs to:

<div>
  <h1>Home</h1>
</div>

Using SVN

If you plan on using SVN instead of Git, you will want to setup some default ignores to make sure you aren't committing extraneous/generated files to your codebase. To do this, adhere to the following steps:

Step 1

Create a new file in the root of your project named .svnignore and give it the following contents:

node_modules
*.log
build
tmp
.grunt
.DS_Store

Step 2

Run the following command:

svn propset svn:ignore -R -F .svnignore .

This command will go through your newly created .svnignore file and set the specified files/folders to be ignored by SVN.

Common Issues

ESLint giving errors for third-party scripts

Typical error message:

jQuery is not defined

When adding third-party scripts, you should always import them to your _scripts/main.js file (See Adding third-party libraries). However, doing so does not inform ESLint that your new library is defined globally. Thus, giving you errors.

Solution

To remedy this situation, all you need to do is open up your .eslintrc file in the root directory of you project, and add your new library name to the global: property array:

// .eslintrc
{
...
  globals: {
    jQuery: true // Tells ESLint that jQuery is defined globally
  }
...
}

Roadmap

Check out the Roadmap to see what's coming down the development pipeline.

Contributing

Anyone and everyone is welcome to contribute. Please take a moment to review the guidelines for contributing.

Testing Generator

To run unit tests, you have a couple options:

npm test: This will run all unit tests with Mocha and send the report to coveralls.io to be processed. (Don't run this for local testing)
npm run localtest: This is the same as npm test only it doesn't send anything to coveralls.io. (Use this for local testing)
npm run localtest-report: This is the same as npm run localtest, but it also generates an HTML report of the current code coverage.

Release History

See Changelog

steadystatic/generator-yeogurt

Yeogurt Generator

Table of Contents

Features

Included in every project

Available Options

Getting Started

Installation

Node.js

Yeoman & Gulp

Yeogurt

Setup

Configuration

Site

Main Directories

Source Directories

Gulp Workflow

gulp

gulp serve

gulp test

Sub-Generators

Default Generators

Page

Example:

Example #2: Specifying a layout

Module

Example:

Layout

Example:

Example #2: Specifying a layout

Guides

Adding third-party libraries

Data Files

Using SVN

Step 1

Step 2

Common Issues

ESLint giving errors for third-party scripts

Typical error message:

Solution

Roadmap

Contributing

Testing Generator

Release History

License

`gulp`

`gulp serve`

`gulp test`