Skip to content

imarc/handbook

Repository files navigation

Handbook

https://handbook.imarc.com

Imarc Handbook documents coding best practices. All pull requests should be made against the gh-pages branch.

Setup

Handbook uses Jekyll, a static-site generator written in Ruby. Your machine likely already has Ruby, but you can install it if needed. You might use Homebrew, for example.

Bundler

If you don’t have Bundler, install it via gem install bundler (you only need to do this once). Then run bundle install. Note: you might need to run these commands as sudo

Node packages

Run npm i to install node packages.

Content Authoring

Edit and save a respective department's markdown file (e.g. frontend.md). See a markdown guide for editing help.

Embeds

As of this writing, we embed Codepen examples. See LastPass for its login credentials. Wrap Codepen embed code in a <div class="emebed"></div> parent for proper spacing. Remove the See the Pen byline copy and the <script>.

Development

Serve Handbook in browser

bundle exec jekyll serve

Watch Sass and JavaScript

npm run watch

HTML class naming

HTML classes are formed following BEM's Two Dashes Style

block-name__elem-name--mod-name

Mobile Nav

mmenu-light is used. We do not apply an mmenu-light "theme" but rather leverage a CSS custom property in src/sass/layouts/_nav-mobile.scss. It works in tandem with Handbook's other light/dark colors in src/sass/base/_root.scss.

Fonts

Handbook uses the Gibson typeface via TypeKit (Adobe Fonts).

Icons

We use Streamline for icons. Specifically, the Streamline Light family.

Images

lazysizes is used for lazy loading and responsive images.

Deployment

You can deploy Handbook by pushing to the gh-pages branch. Remember to run npm run prod before doing so. Handbook uses GitHub Pages for hosting.