Move package documentation to docs site (#389)

* Move icons into separate component * Add sidebar to icon page * Add documentation for packages * Update old markdown files * Update headings in ruby docs * Update dependencies * Add package-lock to octicons_react
primer · Mar 30, 2020 · 83c3b53 · 83c3b53 · vercel · Mar 30, 2020
1 parent 3776160
commit 83c3b53
Show file tree

Hide file tree

Showing 18 changed files with 13,789 additions and 808 deletions.
diff --git a/docs/content/index.mdx b/docs/content/index.mdx
@@ -1,39 +1,10 @@
-import {Flex, Link, TextInput} from '@primer/components'
-import {Container, Head, Header, Hero} from '@primer/gatsby-theme-doctocat'
-import {Search} from '@primer/octicons-react'
-import icons from '../../lib/build/data.json'
-import Icon from '../src/components/icon'
-import useSearch from '../src/use-search'
+---
+title: Octicons
+---
 
-export default function IndexPage() {
-  const [query, setQuery] = React.useState('')
-  const iconsArray = React.useMemo(() => Object.values(icons), [icons])
-  const results = useSearch(iconsArray, query, {keys: ['name']})
-  return (
-    <Flex flexDirection="column" minHeight="100vh">
-      <Head />
-      <Header isSearchEnabled={false} />
-      <Hero />
-      <Container>
-        <TextInput
-          icon={Search}
-          aria-label="Search"
-          value={query}
-          onChange={event => setQuery(event.target.value)}
-          placeholder="Search icons..."
-          width="100%"
-          mb={5}
-        />
-        <Flex flexWrap="wrap" m={-3}>
-          {results.map(icon => (
-            <Link key={icon.name} display="block" p={3} color="inherit" href={icon.name}>
-              <Flex>
-                <Icon name={icon.name} />
-              </Flex>
-            </Link>
-          ))}
-        </Flex>
-      </Container>
-    </Flex>
-  )
-}
+import {HeroLayout} from '@primer/gatsby-theme-doctocat'
+import Icons from '../src/components/icons'
+
+export default HeroLayout
+
+<Icons />
diff --git a/docs/content/packages/index.mdx b/docs/content/packages/index.mdx
@@ -0,0 +1,9 @@
+---
+title: Packages
+---
+
+- [Ruby](/packages/ruby)
+- [Rails](/packages/rails)
+- [Jekyll](/packages/jekyll)
+- [JavaScript](/packages/javascript)
+- [React](/packages/react)
diff --git a/docs/content/packages/javascript.mdx b/docs/content/packages/javascript.mdx
@@ -0,0 +1,131 @@
+---
+title: JavaScript
+status: Stable
+source: 'https://github.com/primer/octicons/tree/master/lib/octicons_node'
+---
+
+[![npm version](https://img.shields.io/npm/v/@primer/octicons.svg)](https://www.npmjs.org/package/@primer/octicons)
+
+## Install
+
+This package is distributed with [npm][npm]. After [installing npm][install-npm], you can install `@primer/octicons` with this command:
+
+```shell
+npm install @primer/octicons
+```
+
+## Usage
+
+For all the usages, we recommend using the CSS located in [`build/build.css`](https://unpkg.com/@primer/octicons/build/build.css). This is some simple CSS to normalize the icons and inherit colors.
+
+After installing `@primer/octicons` you can access the icons like this:
+
+```js
+var octicons = require("@primer/octicons")
+octicons.alert
+// { keywords: [ 'warning', 'triangle', 'exclamation', 'point' ],
+//   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"/>',
+//   height: '16',
+//   width: '16',
+//   symbol: 'alert',
+//   options:
+//    { version: '1.1',
+//      width: '16',
+//      height: '16',
+//      viewBox: '0 0 16 16',
+//      class: 'octicon octicon-alert',
+//      'aria-hidden': 'true' },
+//   toSVG: [Function] }
+```
+
+There will be a key for every icon, with [`toSVG`](#octiconsnametosvg) and other properties.
+
+_Note: `alert` in the above example can be replaced with any valid icon name. Icons with multi-word names (e.g. `arrow-right`) **cannot** be accessed using dot notation (e.g. `octicons.alert`). Instead, use bracket notation (e.g. `octicons['arrow-right']`)._
+
+### `octicons[name].symbol`
+
+Returns the string of the symbol name, same as the key for that icon.
+
+```js
+octicons.x.symbol
+// "x"
+```
+
+### `octicons[name].path`
+
+Returns the string representation of the path of the icon.
+
+```js
+octicons.x.path
+// <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>
+```
+
+### `octicons[name].options`
+
+This is an object of all the attributes that will be added to the output tag.
+
+```js
+octicons.x.options
+// { version: '1.1', width: '12', height: '16', viewBox: '0 0 12 16', class: 'octicon octicon-x', 'aria-hidden': 'true' }
+```
+
+### `octicons[name].width`
+
+Returns 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._
+
+### `octicons[name].height`
+
+Returns 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._
+
+### `keywords`
+
+Returns an array of keywords for the icon. The data comes from the [data file in lib](../data.json). Consider contributing more aliases for the icons.
+
+```js
+octicons.x.keywords
+// ["remove", "close", "delete"]
+```
+
+### `octicons[name].toSVG()`
+
+Returns a string of the `<svg>` tag.
+
+```js
+octicons.x.toSVG()
+// <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>
+```
+
+The `.toSVG()` method accepts an optional `options` object. This is used to add CSS classnames, a11y options, and sizing.
+
+#### class
+
+Add more CSS classes to the `<svg>` tag.
+
+```js
+octicons.x.toSVG({ "class": "close" })
+// <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>
+```
+
+#### aria-label
+
+Add accessibility `aria-label` to the icon.
+
+```js
+octicons.x.toSVG({ "aria-label": "Close the window" })
+// <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>
+```
+
+#### width & height
+
+Size the SVG icon larger using `width` & `height` independently or together.
+
+```js
+octicons.x.toSVG({ "width": 45 })
+// <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>
+```
+
+[primer]: https://github.com/primer/primer
+[docs]: http://primercss.io/
+[npm]: https://www.npmjs.com/
+[install-npm]: https://docs.npmjs.com/getting-started/installing-node
+[sass]: http://sass-lang.com/
diff --git a/docs/content/packages/jekyll.mdx b/docs/content/packages/jekyll.mdx
@@ -0,0 +1,32 @@
+---
+title: Jekyll
+status: Stable
+source: 'https://github.com/primer/octicons/tree/master/lib/octicons_jekyll'
+---
+
+[![Gem version](https://img.shields.io/gem/v/jekyll-octicons.svg)](https://rubygems.org/gems/jekyll-octicons)
+
+This jekyll liquid tag is a plugin that will let you easily include svg octicons in your jekyll sites.
+
+## Install
+
+1. Add this to your `Gemfile`
+
+    ```rb
+    gem 'jekyll-octicons'
+    ```
+
+2. Add this to your jekyll `_config.yml`
+
+    ```yml
+    gems:
+      - jekyll-octicons
+    ```
+
+3. Use this tag in your jekyll templates
+
+    ```
+    {% octicon alert height:32 class:"right left" aria-label:hi %}
+    ```
+
+We recommend including the CSS in the [`@primer/octicons`](/packages/javascript) npm module. You can also npm install that package and include `build/build.css` in your styles.
diff --git a/docs/content/packages/rails.mdx b/docs/content/packages/rails.mdx
@@ -0,0 +1,26 @@
+---
+title: Rails
+status: Stable
+source: 'https://github.com/primer/octicons/tree/master/lib/octicons_helper'
+---
+
+[![Gem version](https://img.shields.io/gem/v/octicons_helper.svg)](https://rubygems.org/gems/octicons_helper)
+
+
+This rails helper lets you easily include svg octicons in your rails apps.
+
+## Install
+
+1. Add this to your `Gemfile`
+
+    ```rb
+    gem 'octicons_helper'
+    ```
+
+3. Use this tag in your erbs
+
+    ```rb
+    <%= octicon "alert", :height => 32,  :class => "right left", :"aria-label" => "hi" %>
+    ```
+
+We recommend including the CSS in the [`@primer/octicons`](/packages/javascript) npm module. You can also npm install that package and include `build/build.css` in your styles.