Status

---

Contents

• Introduction
• Features and Plugins
• Compatibility
• Prerequisites
• Getting Started
• Code Organization
• Automation
• Metadata
• DOM Elements
• Color Palette
• Code Styles
• Got Problems?

---

Introduction

We use a homegrown, content-first boilerplate for GitHub docs. It provides the facilities to write content exclusively in Markdown and spin-up Jekyll-powered static websites, as well as:

• Guaranteeing fast load times
• Automating repetitive tasks
• Rooting responsiveness and accessibility right from its core
• Providing estimated reading times
• Having indexes/table of contents built on-the-fly
• Encoding URLs with the apt labels to help users filter and create issues precisely
• Supporting native instances on Windows 7/8 OSes

back to top

---

Features and Plugins

Below is a list of functional and aesthetic features, baked-in components, and JS plugins.

Core Features

• CSS3
• Grids and MQs from Bootstrap
• HTML5
• Node.js
• Pretty URLs
• Python
• Repository Metadata for GitHub Pages
• Ruby
• Sitemaps.org-compliant sitemap
• Viewports for device and OS support, including iOS 7.1+

Components

• Font Awesome iconic font
• Grunt task runner
• Jekyll for free web hosting using GitHub Pages
• jQuery
• LESS dynamic stylesheets for variables, mixins, nesting, and more
• Liquid templating language with logic tags for self-generating nav links
• Modernizr for legacy- and cross-browser support
• Normalize.css for CSS normalization and resets
• Pygments with a custom theme for code highlighting
• Redcarpet for Markdown-compatibility and rendering
• Universal Analytics with page scroll tracking from Google

Plugins

• Classify DOM utility for class helper functions
• Indexing plugin for building table of contents on-the-fly
• Portfolio plugin for fetching GitHub data using AJAX and JSON
• Readability to make HTML5 more accessible and gauge how long it takes to read a single page
• Scrollable to apply thresholds for HTML elements while scrolling
• Toggle handles the sliding and collapsing behavior for navigation

back to top

---

Compatibility

For the best performance and usability, we recommend the latest versions of the browsers and platforms listed below. As for legacy browsers, the Modernizr plugin does its best but it's not perfect. And like most sites today, we use JS to render on-page elements. If it's disabled in your browser, you might not see those elements.

Starting from the best to the worst, we suggest the following:

• Chrome (~100%)
• Safari (~75%)
• Firefox (~50%)
• Opera (~50%)
• Internet Explorer (~25%)

The table below is a comparison of OS platforms and browsers.

Platform	Chrome	Firefox	Internet Explorer	Opera	Safari
Android	Yes	No	N/A	No	N/A
iOS	Yes	N/A	N/A	No	Yes
Mac OS X	Yes	Yes	N/A	Yes	Yes
Windows	Yes	Yes	Yes	Yes	Yes see note

Note: Apple no longer provides updates for Safari on Windows. Due to the lack of security updates, we do not recommend using Safari on Windows. Use Chrome instead.

back to top

---

Prerequisites

Our boilerplate requires the minimum versions for Ruby, Python, and Node.js. Use the links to get download and install information for your specific OS.

• Ruby 2.0.0
• Python 2.7.6 ^{see note}
• Node.js 0.10.20

Note: Python powers Pygments, which we use for code highlighting. Currently, Pygments 1.6 is not compatible with Python 3. You must have Python 2 installed until Pygments 2.0 is released (date pending).

Windows Users

Read Yi Zeng's Setup Jekyll on Windows article before getting into the thick of things. It will save you a ton of time and agony.

back to top

---

Getting Started

1. Verify that Ruby, Python and Node.js are installed

   # each command returns a version number
   $ ruby -v
   $ python --version
   $ node  --version

2. Clone from GitHub and go into the directory (~5 sec.)

   $ git clone -b gh-pages https://github.com/softlayer/softlayer-python.git
   $ cd softlayer-python

3. Install Grunt (~3 sec.)

   $ [sudo] npm install -g grunt-cli

4. Install modules for Node.js (~15 sec.)

   $ [sudo] npm install

5. Install Jekyll, Pygments and other dependencies (~35 sec.)

   $ [sudo] grunt install

back to top

---

Code Organization

Below is the basic spread for our directory (not including node_modules for Grunt, _site for Jekyll, or any directories made for one-off projects).

├─ _includes/
│   ├─ content/
│   ├─ handlers/
│   └─ partials/
├─ _layout/
├─ assets/
│   ├─ css/
│   ├─ images/
│   ├─ js/
│   └─ packages/
├─ less/
├─ plugins/

5 directories, 7 subdirectories

Directory

Here's an overview of what each directory does or contains.

Directory	Overview
_includes/	Reusable content (“partials”) and semantic HTML elements. {% include file.ext %} tags indicate where partials are being used.
_layouts/	Reusable templates designed for specific uses, like pages, news, articles, and blogs. {{content}} tags inject external content into layouts.
assets/	Static and transpiled resources. This includes JS, CSS, and images.
less/	Source for *.less stylesheets. Bundled LESS files are stored in assets/css.
plugins/	Source for *.js scripts. Bundled JS files are stored in assets/js.

Subdirectory

Here's an overview of each subdirectory.

Subdirectory	Overview
_includes/content/	Reusable, plain-text snippets for documentation.
_includes/handlers/	Logic tags for the Liquid templating engine.
_includes/partials/	Reusable, HTML snippets for documentation and landing pages.
assets/css/	Static directory for bundled CSS resources.
assets/images/	Source for all images, including favicons and logos.
assets/js/	Static directory for bundled JS resources.
assets/packages/	Source for ez_setup.py and get-pip.py.

back to top

---

Automation

We're proponents of DRY (don't repeat yourself). After all, the more automation there is, the less repetitive work you have (and hopefully the less mistakes you make).

Using Grunt, we built a powerful harness that automates ankle-biters like:

• Bundling JS files and transpiling LESS into CSS
• Validating HTML markup
• Installing runtime dependencies for Ruby and Node
• Previewing work locally before pushing it to GitHub

See our list of Grunt Tasks below.

Grunt Tasks

Run any of these commands to initiate a task.

• grunt build
• grunt install
• grunt preview
• grunt serve
• grunt test

Grunt Build

Run grunt build to perform the following:

1. Bundle and minify *.js files using UglifyJS
2. Bundle and minify *.less files to *.css using RECESS

Grunt Install

Run grunt install to perform the following:

1. Install Bundler
2. Read in the Rubygem dependencies from the Gemfile
3. Use Bundler's CLI to install the necessary gems

Grunt Preview

Run grunt preview to perform the following:

1. Build the website locally in the _site directory
2. Start a local environment on http://localhost:4000
3. Regenerate the site whenever files are modified (except JS and LESS stylesheets)

Preview mode lasts forever. It will not timeout after a period of non-usage. In order to kill it, press CTRL+C.

Grunt Serve

This task is a combination of grunt build and grunt preview.

Run grunt serve to perform the following:

1. Bundle and minify *.js files using UglifyJS
2. Bundle and minify *.less files to *.css using RECESS
3. Build the website locally in the _site directory
4. Start a local environment on http://localhost:4000
5. Watch and regenerate a new _site directory whenever a file is modified (except JS and LESS stylesheets)

Just like with grunt preview, serve mode lasts forever. It will not timeout after a period of non-usage. In order to kill it, press CTRL+C.

Grunt Test

Run grunt test to perform the following:

1. Build the website locally in the _site directory
2. Test all *html files against W3's HTML validation service
3. Spit out logs

Updating Grunt Dependencies

Dependencies are updated often by their original authors. To keep up with them, we test and update the version levels in package.json. However, dependencies do not update themselves automatically. To install the most recent versions, run the following commands to delete the original node_modules directory and build a new one.

$ [sudo] rm -r node_modules
$ [sudo] npm install

back to top

---

DOM Elements

Several DOM elements are embedded within JS and render on the home/landing page. The table below provides the name and purpose of each element (in alphabetical order).

DOM Elements	Purpose
#github-contributors	Total number of contributors for a single repo
#github-repos	Total number of repos for a single organization
#github-stargazers	Total number of stargazers for a single repo
#github-version	Version number for the last pegged released
#github-watchers	Total number of watchers/subscribers for a single repo

back to top

---

Metadata

We harness several metadata tags using GitHub's repository metadata feature, albeit not all of them for a number of reasons.

Below is a list of metadata tags we use.

Metadata Tags	Example
{{site.github.issues_url}}	http://github.com/softlayer/softlayer-python/issues
{{site.github.owner_url}}	http://github.com/softlayer
{{site.github.project_tagline}}	"A set of Python libraries that assist in calling the SoftLayer API."
{{site.github.releases_url}}	http://github.com/softlayer/softlayer-python/releases
{{site.github.repository_url}}	http://github.com/softlayer/softlayer-python
{{site.github.url}}	http://softlayer.github.io/softlayer-python

back to top

---

Color Palette

The colors below correspond with their respective LESS @xxxx variables.

Colors

Base Colors

back to top

---

Code Styles

Use the settings below to help unify coding styles across different editors.

• indent_style = space
• end_of_line = lf
• charset = utf-8
• trim_trailing_whitespace = true
• insert_final_newline = false
• indent_size = 4

Sublime Text users can configure these settings manually by opening Preferences > Settings - User, inserting the lines below, and saving your settings.

{
  "translate_tabs_to_spaces": true,
  "tab_size": 4,
  "ensure_newline_at_eof_on_save": false,
  "default_encoding": "UTF-8",
  "default_line_ending": "lf",
  "trim_trailing_white_space_on_save": true
}

Sublime Packages

Sublime does not include every syntax highlight. To get certain highlights, you have to install them by hand. The instructions below delve into the install processes for Jekyll, LESS, and Liquid.

Use Package Control, Sublime's built-in tool, to install these syntaxes. If you already have Package Control, skip the rest of this and click any of the links below. If you don't, this install guide will walk you through all the install options. Once that's done, click any of these links:

• Jekyll
• LESS
• Liquid

Jekyll

1. Open Preferences > Package Control.
2. Type Install Package and hit return.
3. Type Jekyll and hit return.

The Jekyll package includes syntaxes for HTML, JSON, Markdown, and Textile.

LESS

1. Open Preferences > Package Control.
2. Type Install Package and hit return.
3. Type LESS and hit return.

Liquid

1. Open Preferences > Package Control.
2. Type Install Package and hit return.
3. Type Siteleaf Liquid Syntax and hit return.

The Liquid package includes syntax for HTML.

back to top

---

Got Problems?

Below are a few issues and solutions (or workarounds) that we came across during development.

Incompatible character encodings

If you get Liquid Exception: incompatible character encodings: UTF-8 and IBM437... after running grunt serve, this means your CLI does not use UTF-8 by default (example: Git for Windows). A workaround is to run the following commands before running grunt serve.

$ cmd
$ chcp 65001
$ exit

Note: You only need to run these commands when you first open your CLI. The settings persist locally until you close it.

Conversion error

If you're getting a Conversion error: There was an error converting file_name.md" message, this means a HTML tag is not closed. To fix this, close all HTML tags.

Tip: Run grunt test to help find the open tag.

Liquid Exception: Cannot find /bin/sh

If you're getting a Liquid Exception: Cannot find /bin/sh, this means you have a buggy version of pygments.rb. A workaround is to use pygments.rb version 0.5.0. This means you'll have to uninstall newer versions as well. To do this, run the following commands.

$ gem uninstall pygments.rb --version "=0.5.4"
$ gem uninstall pygments.rb --version "=0.5.2"
$ gem uninstall pygments.rb --version "=0.5.1"
$ gem install pygments.rb --version "=0.5.0"

Not Found: '/' not found

If you're getting a '/' not found error when you open a browser to localhost:4000, this means something went wrong when Jekyll created the _site directory. It has nothing to do with you, it's all Jekyll. To fix this, type CTRL+C to stop Jekyll and try again.

Warning: cannot close fd before spawn

If you get Warning: cannot close fd before spawn after running grunt serve, this means something went wrong when Jekyll created the _site directory. It has nothing to do with you, it's all Jekyll. To fix this, run grunt serve again.

back to top