N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

J U S T I N S L A C K

F R O N T - E N D S T Y L E G U I D E S W I T H J E K Y L L

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

WHAT IS A FRONT-END STYLE GUIDE AND WHAT IS IT FOR?

•Style guides are the perfect place to start a website build and modular base. They bridge the gap between design and development. 

•Style guides show the design elements you have at your disposal.

•Style guides show the design elements you lack.

•Style guides provide an accessible baseline on which to build upon.

•Style guides allow you to test code early in browsers and on devices.

•Style guides leave a design & build blueprint for future development.

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

WHAT IS A FRONT-END STYLE GUIDE AND WHAT IS IT FOR?

•Style guides set a precedent, demonstrating how designers or developers expect something to be done in future.

•Style guides are useful when several people are working on the same codebase

•Style guides encourage consistency

•Style guides make maintaining a site easier

•Style guides use real code and run in the browser

•A style guide can be a living document that grows with a site over time

•A style guide helps prevent duplication of code and design patterns.

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

STYLE GUIDE EXAMPLES

•Clearleft

•Github

•Pattern lab

•Mailchimp

•Atlassian

•Lonely Planet

•And many more

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

STYLE GUIDE GENERATION OPTIONS

•KSS - rails

•Tomdoc - ruby

•Pattern Primer - one of many PhP options

•Lots of javascript options

•None of the above

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

WHAT IS JEKYLL?

• Jekyll is a parsing engine bundled as a ruby gem !

• It is used to build static sites from dynamic components such as templates, partials, liquid code and markdown. !

• Jekyll is billed as "a simple, blog aware, static site generator”.

• Powers GitHub pages

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

JEKYLL REQUIREMENTS

•Ruby

•Ruby gems

•NodeJS

•Linux, Unix, or Mac OS X

•Not officially supported on Windows but it can be run

•Mac OS X - probably need to install xCode’s command line tools.

!

~ $ gem install jekyll ~ $ jekyll new my-awesome-site ~ $ cd my-awesome-site ~/my-awesome-site $ jekyll serve !

# => Now browse to http://localhost:4000

INSTALLING JEKYLL

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

!

$ jekyll build # => The current folder will be generated into ./_site !

$ jekyll build --destination <destination> # => The current folder will be generated into <destination> !

$ jekyll build --watch # => The current folder will be generated into ./_site, # watched for changes, and regenerated automatically.

BASIC USAGE

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

The Jekyll gem makes a jekyll executable available to you in your Terminal window. You can use this command in a number of ways:

$ jekyll serve # => A development server will run at http://localhost:4000/ !

$ jekyll serve --watch # => Same as `jekyll serve`, but watch for changes and regenerate automatically.

DEVELOPMENT SERVER

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

•Jekyll comes with a built-in development server, allowing local previews of your site.

!

├── _config.yml ├── _drafts ├── _assets ├── _includes ├── _layouts ├── _posts ├── _site └── index.html

DIRECTORY STRUCTURE

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

name: Site name main_title: Site title markdown: redcarpet highlighter: pygments permalink: /:title

CONFIGURATION

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

Jekyll allows you to configure your sites in many different ways thanks to the powerful and flexible configuration options.

YEAR-MONTH-DAY-title.MARKUP !

eg. 2014-07-31-we-are-going-to-a-meet-up.md

CREATING POSTS

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

To create a new post, all you need to do is create a new file in the _posts directory.

How you name files in this folder is important. Jekyll requires blog post files to be named according to the following format:

YEAR-MONTH-DAY-title.MARKUP !

2014-07-31-we-are-going-to-a-meet-up.md

CREATING POSTS

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

To create a new post, all you need to do is create a new file in the _posts directory.

How you name files in this folder is important. Jekyll requires blog post files to be named according to the following format:

{% highlight css %} .submit-button:hover { box-shadow: 0 -2px 10px 0 rgba(0, 0, 0, 0.1); text-decoration: none; } {% endhighlight %}

SYNTAX HIGHLIGHTING

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

Jekyll has built in support for syntax highlighting of over 100 languages thanks to Pygments.

To use Pygments, you must have Python installed on your system and set highlighter option to pygments in your site’s configuration file.

N E W M E D I A L A B S . C O . Z A • @ U R B A N R E N E WA L • J U S T I N @ N E W M E D I A L A B S . C O . Z A

ISSUES WITH THIS APPROACH

•Not a living style guide

•If CSS, js or HTML changes it needs updating in two places

•Hard to demonstrate responsive layouts

•You are building two sites - your actual site plus your style guide framework - making it operative that there are no conflicts in your CSS or HTML.

•Jekyll problems

•Slow

•Build issues