Readme

Sabre Spark Style Guide

Site Generator Migration

To serve files locally:

  • bundle install
  • npm install
  • grunt dev

Dependencies

This project was built and tested to work with:

  • ruby 2.2.3
  • npm 2.7.3
  • node v4.2.1

Distribution

Project

How to work with and build this project:

  • git clone spark/unzip a download of the code-base and the spark library
  • bundle install
  • npm install
  • grunt dist

Note: Do not use the native command line jekyll build command. Instead use grunt to build the site. Grunt uses jekyll to build the site, once all the appropriate tasks have been run first.

Note: You will need a separate directory to store and link in the Spark EDL. A typical environment looks like:


	/* Root directory for storing new sabre spark site */
	~/Projects/sabre-spark-site

	/* Directory for storing the spark edl assets and patterns (css,js,scss) */
	~/Projects/sabre-spark-site/spark-lib/

	/* Directory of this project. */
	~/Projects/sabre-spark-site/spark-jekyll-website/

For the above example, the npm link command would be:


	cd ~/Projects/sabre-spark-site/spark-jekyll-website/
	npm link ../spark-lib

This will install and link all the necessary dependencies for building the project.

Grunt will then copy the necessary files before executing the jekyll build service. Grunt will also serve the static web site.

Website

How to build and distribute the compiled environment:

@TODO: Implement a true distribution grunt task

This will clean the project and build for distribution. The _site folder can then be copied to a static web server. This part of the process is intentionally left up to the distributor.

Development

During the development process, you can use Grunt's watch and LiveReload function to automatically build and serve the static files when changes are saved.

  • grunt dev

Contribute Effectively

Project Structure

The main components of the Spark Style Guide with jekyll. The project is using jekyll 3.0 w/ collections.

Per jekyll, each directory in the root folder, starting with an underscore ( _ ) will not be copied into the compiled website folder ( _site ).

_components__ui : This is where the html or markdown pages for each ui component lives. Each component is built to be rendered as its own page.

_components__design : This is where the html or markdown pages for each design principle lives

_includes : Snippets of HTML/Liquid which are reused throughout the site

_layouts : Similar to includes, in that the the Snippets are reused, however they are designed to be containers, piecing the _includes together.

_plugins : Ruby files for jekyll plugins, used to extend the rendering functionality of jekyll

_sass : Where the sass files of the Style Guide website live.

_site : The directory which the site is built to by jekyll. This folder can be copied over onto any static web server.

css & js : These folders contain the css and js for the jekyll website. During the build process, the css and js from the spark edl are copied into these folders. Then these folders are directly copied into the compiled website folder ( _site ).

design & demo & ui : These folders are one off pages. They are used to store only an index.(html|md) file which will be added to the navigation of the website.

Notable Files

The project is setup to be very modular. Many parts can be swapped out for alternatives without changing the functions of other parts. This means there are a few config files to get everything situated. All config files live in the root directory.

Gemfile : This is our standard gem file to keep track of dependencies and make distributing the project more consistent.

package.json : Another set of dependencies needed to be tracked (mostly for grunt and the different plugins).

Gruntfile.js : The main file for the build process. Grunt takes all the different components and makes sure they work together.

_config.yml : Config file for the jekyll gem.

.editorconfig : Useful for keeping coding styles consistent. Your specific editor of choice may need a plugin to take use of this file.

.jshintrc : Rules for javascript files to follow. Checked during the grunt tasks. Your specific editor of choice may need a plugin to take use of this file.

README.md : Document the project and include useful information other developers or designers might need to know about.

Adding to Spark

Visit the Spark EDL repository to update the core Spark EDL.

To update the documentation of a Spark Component:

HTML/Markdown : Add your component specific markup to the _components__<design or ui>/$component.markdown .