externals/octicons/README.md

   1 # GitHub Octicons
   2
   3 [![NPM version](https://img.shields.io/npm/v/octicons.svg)](https://www.npmjs.org/package/octicons)
   4 [![Build Status](https://travis-ci.org/primer/octicons.svg?branch=master)](https://travis-ci.org/primer/octicons)
   5
   6 > Octicons are a scalable set of icons handcrafted with <3 by GitHub.
   7
   8 ## Install
   9
  10 **NOTE:** The compiled files are located in `/build/`. This directory is located in the published npm package. Which means you can access it when you `npm install octicons`. You can also build this directory by following the [building octicons directions](#building-octicons). The files in the `/lib/` directory are the raw source files and are not compiled or optimized.
  11
  12 #### NPM
  13
  14 This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `octicons` with this command.
  15
  16 ```
  17 $ npm install --save octicons
  18 ```
  19
  20 ## Usage
  21
  22 For all the usages, we recommend using the CSS located in `./build/octicons.css`. This is some simple CSS to normalize the icons and inherit colors.
  23
  24 ### Spritesheet
  25
  26 With a [SVG sprite icon system](https://css-tricks.com/svg-sprites-use-better-icon-fonts/) you can include the sprite sheet located `./build/sprite.octicons.svg` after you [build the icons](#building-octicons) or from the npm package. There is a demo of how to use the spritesheet in the build directory also.
  27
  28 ### Node
  29
  30 After installing `npm install octicons` you can access the icons like this.
  31
  32 ```js
  33 var octicons = require("octicons")
  34 octicons.alert
  35 // { keywords: [ 'warning', 'triangle', 'exclamation', 'point' ],
  36 //   path: '<path d="M8.865 1.52c-.18-.31-.51-.5-.87-.5s-.69.19-.87.5L.275 13.5c-.18.31-.18.69 0 1 .19.31.52.5.87.5h13.7c.36 0 .69-.19.86-.5.17-.31.18-.69.01-1L8.865 1.52zM8.995 13h-2v-2h2v2zm0-3h-2V6h2v4z"/>',
  37 //   height: '16',
  38 //   width: '16',
  39 //   symbol: 'alert',
  40 //   options:
  41 //    { version: '1.1',
  42 //      width: '16',
  43 //      height: '16',
  44 //      viewBox: '0 0 16 16',
  45 //      class: 'octicon octicon-alert',
  46 //      'aria-hidden': 'true' },
  47 //   toSVG: [Function] }
  48 ```
  49
  50 There will be a key for every icon, with `keywords` and `svg`.
  51
  52 #### `octicons.alert.symbol`
  53
  54 Returns the string of the symbol name
  55
  56 ```js
  57 octicons.x.symbol
  58 // "x"
  59 ```
  60
  61 #### `octicons.person.path`
  62
  63 Path returns the string representation of the path of the icon.
  64
  65 ```js
  66 octicons.x.path
  67 // <path 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"></path>
  68 ```
  69
  70 #### `octicons.issue.options`
  71
  72 This is a json object of all the `options` that will be added to the output tag.
  73
  74 ```js
  75 octicons.x.options
  76 // { version: '1.1', width: '12', height: '16', viewBox: '0 0 12 16', class: 'octicon octicon-x', 'aria-hidden': 'true' }
  77 ```
  78
  79 #### `octicons.alert.width`
  80
  81 Width is the icon's true width. Based on the svg view box width. _Note, this doesn't change if you scale it up with size options, it only is the natural width of the icon_
  82
  83 #### `octicons.alert.height`
  84
  85 Height is the icon's true height. Based on the svg view box height. _Note, this doesn't change if you scale it up with size options, it only is the natural height of the icon_
  86
  87 #### `keywords`
  88
  89 Returns an array of keywords for the icon. The data [comes from the octicons repository](https://github.com/primer/octicons/blob/master/lib/data.json). Consider contributing more aliases for the icons.
  90
  91 ```js
  92 octicons.x.keywords
  93 // ["remove", "close", "delete"]
  94 ```
  95
  96 #### `octicons.alert.toSVG()`
  97
  98 Returns a string of the svg tag
  99
 100 ```js
 101 octicons.x.toSVG()
 102 // <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path 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>
 103 ```
 104
 105 The `.toSVG()` method accepts an optional `options` object. This is used to add CSS classnames, a11y options, and sizing.
 106
 107 ##### class
 108
 109 Add more CSS classes to the `<svg>` tag.
 110
 111 ```js
 112 octicons.x.toSVG({ "class": "close" })
 113 // <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x close" aria-hidden="true"><path 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>
 114 ```
 115
 116 ##### aria-label
 117
 118 Add accessibility `aria-label` to the icon.
 119
 120 ```js
 121 octicons.x.toSVG({ "aria-label": "Close the window" })
 122 // <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-label="Close the window" role="img"><path 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>
 123 ```
 124
 125 ##### width & height
 126
 127 Size the SVG icon larger using `width` & `height` independently or together.
 128
 129 ```js
 130 octicons.x.toSVG({ "width": 45 })
 131 // <svg version="1.1" width="45" height="60" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path 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>
 132 ```
 133
 134 #### `octicons.alert.toSVGUse()`
 135
 136 Returns a string of the svg tag with the `<use>` tag, for use with the spritesheet located in the /build/ directory.
 137
 138 ```js
 139 octicons.x.toSVGUse()
 140 // <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><use xlink:href="#x" /></svg>
 141 ```
 142
 143 ### Ruby
 144
 145 If your environment is Ruby on Rails, we have a [octicons_helper](https://github.com/primer/octicons_helper) gem available that renders SVG in your page. The octicons_helper uses the [octicons_gem](https://github.com/primer/octicons_gem) to do the computing and reading of the SVG files.
 146
 147 ### Jekyll
 148
 149 For jekyll, there's a [jekyll-octicons](https://github.com/primer/jekyll-octicons) plugin available. This works exactly like the octicons_helper.
 150
 151 ## Changing, adding, or deleting icons
 152
 153 1. Open the [Sketch document][sketch-document] in `/lib/`. Each icon exists as an artboard within our master Sketch document. If you’re adding an icon, duplicate one of the artboards and add your shapes to it. Be sure to give your artboard a name that makes sense.
 154 2. Once you’re happy with your icon set, choose File > Export…
 155 3. Choose all the artboards you’d like to export and then press “Export”
 156 4. Export to `/lib/svg/`
 157
 158 You’ll next need to build your Octicons.
 159
 160 ## Building Octicons
 161
 162 All the files you need will be in the `/build/` directory already, but if you’ve made changes to the `/lib/` directory and need to regenerate, follow these steps:
 163
 164 1. Open the Octicons directory in Terminal
 165 2. `npm install` to install all dependencies for the project.
 166 3. Run the command `npm run build`. This will run the grunt task to build the SVGs, placing them in the `/build/` directory.
 167
 168 ## Publishing
 169
 170 If you have access to publish this repository, these are the steps to publishing. If you need access, contact [#design-systems](https://github.slack.com/archives/design-systems).
 171
 172 1. Update the [CHANGELOG.md](./CHANGELOG.md) with relevant version number and any updates made to the repository.
 173 2. `npm version <newversion>` Run [npm version](https://docs.npmjs.com/cli/version) inputing the relevant version type. The versioning is [semver](http://semver.org/), so version appropriately based on what has changed.
 174 3. `npm publish` This will publish the new version to npmjs.org
 175 4. `git push && git push --tags` Push all these changes to origin.
 176
 177 ## License
 178
 179 (c) 2012-2016 GitHub, Inc.
 180
 181 When using the GitHub logos, be sure to follow the [GitHub logo guidelines](https://github.com/logos).
 182
 183 _SVG License:_ [SIL OFL 1.1](http://scripts.sil.org/OFL)
 184 Applies to all SVG files
 185
 186 _Code License:_ [MIT](./LICENSE)
 187 Applies to all other files
 188
 189 [primer]: https://github.com/primer/primer
 190 [docs]: http://primercss.io/
 191 [npm]: https://www.npmjs.com/
 192 [install-npm]: https://docs.npmjs.com/getting-started/installing-node
 193 [sass]: http://sass-lang.com/
 194 [sketch-document]: https://github.com/primer/octicons/blob/master/lib/octicons-master.sketch