YeoRS Generator

...a fork of Yeogurt. Less options, more opinionated; also contains Foundation.

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

Table of Contents

• Features
• Getting Started
• Setup
• Gulp Workflow
• Sub-Generators
• Guides
• License

Features

Included in every project

• Preview server with Browsersync
• Automated build process that includes: compilation of preprocessors (Sass), 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 JavaScript Standard Style
• Foundation

Available Options

• Project/Site naming

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

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.

NOTE: For Windows users You may have some issues compiling BrowserSync during installation of packages. Please go to http://www.browsersync.io/docs/#windows-users for more information on how to get all the needed dependencies.

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 --version | 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.

YeoRS

Now that you have all the needed dependencies, you can install this generator by cloning it, then running:

npm install
npm link

Later we'll use the following command: npm install -g generator-yeors

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

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 YeoRS generator.

yo yeors

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 yeors --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:

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

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

Now you can run the following gulp tasks:

• npm run devel or gulp devel for previewing your site/app on a development server.
• gulp devel --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.
• npm run dist or gulp dist for copying all of the css files to final output folder.

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

Configuration

Configuration of folders and filenames is possible, although discouraged.

Gulp Workflow

gulp --production

Runs gulp test and builds out an optimized site through compilation of preprocessors (Jade, Sass, etc), minification of CSS and HTML, uglification of Javascript, and optimization of images.

npm run devel or gulp devel

Starts up a development server that watches files and automatically reloads them to the browser when a change is detected. There's a slight difference between commands: npm run devel doesn't require gulp to be globally installed and it opens the browser, too.

Extra Task Target(s)

|Tasks| Description |---------|------- |gulp devel --production| starts up a server that loads a production version of the site |npm run devel or gulp devel --open| starts up a server and opens it within your default browser

gulp test

Runs 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

Adding the --debug option to any gulp task displays extra debugging information (ex. data being loaded into your templates)

Sub-Generators

• yeors:page
• yeors:module
• yeors:layout

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

Default Generators

Page

Creates a new page.

Example:

$ yo yeors:page contact

Produces:

src/contact/index.nunjucks

Example #2: Specifying a layout

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

Produces:

// Page that extends from 'src/_layouts/one-col'
src/contact/index.nunjucks

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

Module

Creates a new module.

Example:

$ yo yeors:module header

Produces:

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

Example #2: Specifying module as atomic

This is a great way to create modules that adhere to atomic design

$ yo yeors:module link --atomic=atom

Produces:

src/_modules/atoms/header/header.,nunjucks
src/_modules/atoms/header/header.{scss,sass,less,styl}
src/_modules/atoms/header/header.js
src/_modules/atoms/header/__tests__/header.test.js

NOTE: Possible --atomic options: atom, molecule, organism

Layout

Creates a new layout.

Example:

$ yo yeors:layout one-col

Produces:

src/_layouts/one-col.nunjucks

Example #2: Specifying another layout to extend from

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

Produces:

// Layout that extends from 'src/_layouts/one-col'
src/contact/index.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

Stylesheets

You can also access stylesheets by importing them to your preprocessor like so:

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

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

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:

 site.data.menu.name

Which outputs to:

Home

Original license (derived from)

MIT License - © Jake Larson

License

Licensed - © Renderspace d.o.o; Samo Fabčič; Dragan Petoš