Developing with the Armadillo - Snugug/gulp-armadillo GitHub Wiki

Pre Setup

Before we get started, the following items need to be installed on your computer. You will need Git and Node 6 or better on your computer to run Armadillo. There are some optional installs as well, if you'd like.

Installing Git

Git - Check to see if it's installed by running git --help in your terminal

Installing Node

Apple Computer

  1. Homebrew - Check to see if it's installed by running brew -h in your terminal
  2. NVM - Install by running brew install nvm in your terminal.
  3. Run touch ~/.bash_profile, then open ~/.bash_profile. This will create and open a file that allows your terminal to be set up. If you know you are running a different terminal, open that terminal's profile file (for instance, ZSH's file is ~/.zshrc).
  4. Add the following to your ~/.bash_profile file: export NVM_DIR=~/.nvm source $(brew --prefix nvm)/nvm.sh, each on separate lines. Save the file, close your terminal, and restart it.
  5. Node.js - Install by running nvm install v6 in your terminal.
  6. Add nvm use v6 on a new line to the same file you edited in Step 3. Save, close, and re-open your terminal

Windows Computer

  1. NVM for Windows
  2. Node.js - Install by running nvm install v6 in your terminal.
  3. Run nvm use v6 to start Node when you want to use it

Linux Computer

  1. NVM - Check to see if it's installed by running nvm -h
  2. Run touch ~/.bash_profile, then open ~/.bash_profile. This will create and open a file that allows your terminal to be set up. If you know you are running a different terminal, open that terminal's profile file (for instance, ZSH's file is ~/.zshrc).
  3. Add the following to your ~/.bash_profile file: export NVM_DIR=~/.nvm source $(brew --prefix nvm)/nvm.sh, each on separate lines. Save the file, close your terminal, and restart it.
  4. Node.js - Install by running nvm install v6 in your terminal.
  5. Add nvm use v6 on a new line to the same file you edited in Step 2. Save, close, and re-open your terminal

Optional Gulp Install

Once Node is installed on your system, you can optionally install Gulp globally, which will be used to run Armadillo. To install, run the following from your command line:

npm install -g gulp

Optional Bower Install

One of Armadillo's opinions is using Bower to install front-end dependencies. Check to see if it's installed by running bower -h, otherwise you can install it.

Optional Yeoman Generator Install

Instead of training your Armadillo manually as described below, you can use the latest Armadillo Generator for Yeoman. To do so, run the following from your command line:

npm install -g yo generator-armadillo

Setup

If you have the Yeoman Generator installed, setup is a breeze! From your command line, run yo armadillo and follow the Armadillo's instructions! Then, you're all set!

Otherwise, by default, the following folder structure should be used. Items with a * are optional. Items ending in / are folders:

|-- Gulpfile.js
|-- config/
  |-- default.js
|-- package.json
|-- pages/
|-- templates/
|-- sass/
|-- js/
|-- images/
|-- videos/
|-- audio/
|-- fonts/
|-- documents/
|-- CNAME*
|-- manifest.json*

Gulpfile.js

This is your Gulpfile for actually running the Armadillo! It should look like this:

'use strict';

//////////////////////////////
// Require Gulp and grab Armadillo
//////////////////////////////
var gulp = require('gulp');

require('gulp-armadillo')(gulp);

That's it!

package.json

Your NPM config files. Configure to your liking, but be sure to require both Gulp and Gulp Armadillo in your package.json's dependencies!

npm install gulp gulp-armadillo --save-dev

Pages Folder

All of your pages, the actual URLs and their content that will be displayed, will go in here. You can either write HTML or GitHub Flavored Markdown files, and either will render. If you'd like to add additional structured information for a page beyond the content, you can add Front Matter before the content for a page

Templates

All pages can be wrapped in, and include, Nunjucks templates. The Templates directory is where those templates should live. Pages can use templates and Nunjucks directly, or a page can include in its Front Matter a template key that will automatically extend the named template and place the content (rendered for Markdown) in a block called content.

template: 'template.html'

Remaining Folders

All remaining folders should contain their respective file types. Sass, JavaScript, images, fonts, audio files, video files, and documents. Sass files will be compiled to CSS, JavaScript files linted, images optimized, and the rest copied around.