helper-octicon

Template helper for displaying octicon SVGs. Should work with any Handlebars, Lo-Dash, underscore or any template engine that allows helper functions to be registered. Also compatible with verb, assemble, and templates.

Install

Install globally with npm

$ npm install --global helper-octicon

Usage

The main export is a function that can be called directly:

var octicon = require('helper-octicon');
console.log(octicon('x'));
//=> '<svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path fill-rule="evenodd" d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>'

Examples

With Handlebars:

use triple curly braces to unescape the svg tag so it's rendered correctly.

{{{octicon "x" class="close"}}}
//=> <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x close" aria-hidden="true"><path fill-rule="evenodd" d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>

Usage with assemble

(This example also works for verb, update, generate, or any other lib based on the templates library)

Register the helper for use with any template engine

var templates = require('templates');
var app = templates();

app.helper('octicon', require('helper-octicon'));

app.task('default', function() {
  app.src('templates/.hbs')
    .pipe(app.dest('dist'));
});

Helper usage

Delimiters depend on the engine registered. For example, with Lo-Dash or Underscore templates:

<%= octicon("x") %>
//=> <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path fill-rule="evenodd" d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>

Or with Verb, which uses special delimiters to avoid delimiter collision when the documentation itself includes templates that should not render (like these docs):

{%= octicon("x") %}
//=> <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path fill-rule="evenodd" d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>

Usage with handlebars

To use the helper directly with handlebars:

var handlebars = require('handlebars');
handlebars.registerHelper('octicon', require('helper-octicon'));

Template examples:

{{{octicon "x"}}}
{{{octicon "x" class="close"}}}
{{{octicon "x" width="48" height="60"}}}

Usage with lodash or underscore

Use directly with Lo-Dash or underscore:

var octicon = require('helper-octicon');

// as a mixin
_.mixin({octicon: octicon});
_.template('<%= _.octicon("x") %>');
//=> '<svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path fill-rule="evenodd" d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>'

// or pass the helper on the context
_.template('<%= octicon("x") %>')({octicon: octicon});
//=> '<svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path fill-rule="evenodd" d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>'

To contribute a helper to the github.com/helpers org, follow these steps:

1. Install the helper generator

Install generate and [generate-helper][]:

npm install --global generate generate-helper

2. Generate your project

To initialize the project, including documentation and unit tests, in the command line, run:

gen helper

3. Create a repo

Create a repo on GitHub under your own account.

4. Last, request a transfer

Create an issue to request a transfer to the helpers org.

About

Related projects

• assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
• engine: Template engine based on Lo-Dash template, but adds features like the ability to register helpers… more | homepage
• generate: Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… more | homepage
• handlebars-helpers: More than 130 Handlebars helpers in ~20 categories. Helpers can be used with Assemble, Generate… more | homepage
• octicons: A scalable set of icons handcrafted with <3 by GitHub. | homepage
• templates: System for creating and managing template collections, and rendering templates with any node.js template engine… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for avice on opening issues, pull requests, and coding standards.

Building docs

(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Brian Woodward

• github/doowb
• twitter/doowb

License

Copyright © 2017, Brian Woodward. Released under the MIT license.

This file was generated by verb-generate-readme, v0.2.3, on January 04, 2017.