Release 12.6.0

.storybook/preview-head.html

@@ -1,2 +1,3 @@
 <link rel="stylesheet" href="https://unpkg.com/octicons@8.5.0/build/build.css">
+<link rel="stylesheet" href="https://github.com/site/assets/styleguide.css">
 <script src="https://github.com/site/assets/styleguide.js" async></script>

DEVELOP.md

@@ -36,7 +36,7 @@ The typical Primer workflow looks something like this:
 Run `npm install` to install the npm dependencies.
 
 ## Docs site
-The Primer CSS docs are built with React using [Primer Components](https://primer.style/components) and automatically deployed on every push to this repo using our [primer/deploy action](/primer/deploy). You can run the server locally with:
+The Primer CSS docs are built with React using [Primer Components](https://primer.style/components) and automatically deployed on every push to this repo with [Now]. You can run the server locally with:
 
 ```sh
 npm start
@@ -73,29 +73,27 @@ This should open up the site in your browser (if not, navigate to `http://localh
 ### Code blocks
 All `html` fenced code blocks in `src/**/*.md` will be rendered as stories and listed under the relevant module's name in the left-hand nav. File changes should trigger a live reload automatically (after a brief delay).
 
-Note: At this time, we do not load any stories from `src/**/stories.js`.
 
 ## Scripts
-Our [`package.json`](package.json) houses a collection of [run-scripts] that we use to maintain, test, build, and publish Primer CSS, notably:
+Our [`package.json`](package.json) houses a collection of [run-scripts] that we use to maintain, test, build, and publish Primer CSS. Run `npm run <script>` with any of the following values for `<script>`:
 
+* `fresh` does a "fresh" npm install (like `npm install -f`)
 * `dist` runs `script/dist`, which creates CSS bundles of all the `index.scss` files in `src/`.
 * `check-links` runs a link checker on your local development server (`localhost:3000`, started with `npm start`).
-* `lint` lints all of our SCSS source files.
-* `lint-js` lints the docs site and supporting scripts.
+* `lint` lints both our SCSS and JavaScript source files.
+* `lint-css` lints our SCSS source files.
+* `lint-js` lints the JavaScript source files.
 * `now-build` and `now-start` are run on [Now] to build and start the docs site server. `now-test` runs them both in order.
-* `test-urls` compares a (pre-generated) list of paths from the [Primer Style Guide](https://styleguide.github.com/primer/) to files in `pages/css`, and lets us know if we've inadvertently deleted or renamed anything.
+* `start` runs the documentation site locally (alias: `dev`).
+* `test-urls` compares a (pre-generated) list of paths from the **deprecated** [Primer Style Guide](https://styleguide.github.com/primer/) to files in `pages/css`, and lets us know if we've inadvertently deleted or renamed anything.
 * `test-migrate` tests the [`primer-migrate`](MIGRATING.md#primer-migrate) command line utility.
-* `watch` runs the sync script in watch mode, copying files as they're changed from `src/` to `pages/css/`.
 
-You can list all of the available scripts with:
-
-```sh
-npm run
-```
+The above list may not always be up-to-date. You can list all of the available scripts by calling `npm run` with no other arguments.
 
 
 [@primer/css]: https://www.npmjs.com/package/@primer/css
 [run-scripts]: https://docs.npmjs.com/cli/run-script
 [storybook]: https://storybook.js.org/
+[now]: https://zeit.co/now
 [npm]: https://www.npmjs.com/
 [npx]: https://www.npmjs.com/package/npx

lib/erb-to-html.js

@@ -0,0 +1,91 @@
+/* eslint-disable no-console */
+const visit = require('unist-util-visit')
+const cache = new Map()
+const ERB_BLOCK_PATTERN = /<%=[^%]+%>/g
+
+module.exports = options => {
+  const convert = converter(options)
+  return tree => {
+    visit(tree, 'code', node => {
+      const match = node.lang ? node.lang.match(/^[a-z]+/) : null
+      const lang = match ? match[0] : null
+      if (lang === 'erb' || lang === 'html') {
+        const erb = node.value
+        const html = convert(erb)
+        const remaining = html ? html.match(ERB_BLOCK_PATTERN) : null
+        if (html && !remaining) {
+          node.value = html
+          node.lang = node.lang.replace(/^erb/, 'html')
+        } else if (remaining) {
+          // console.warn(`Unable to convert ${remaining.length} ERB blocks:\n  ${remaining.join('  \n')}`)
+        } else {
+          // console.warn(`No conversions made in: ${erb}`)
+        }
+      } else {
+        // console.warn(`Unknown code block lang: ${node.lang}`)
+      }
+    })
+  }
+}
+
+function converter({methods = {}}) {
+  return erb => {
+    const blocks = erb.match(ERB_BLOCK_PATTERN)
+    if (blocks && blocks.length) {
+      let html = erb
+      // console.warn(`Replacing ${blocks.length} ERB block(s)...`)
+      for (const block of blocks) {
+        const output = convert(block)
+        if (output !== block) {
+          // const count = html.split(block).length - 1
+          // console.warn(`  found ${count} instances of "${block}"`)
+          html = replaceAll(html, block, output)
+          // console.warn(html)
+        }
+      }
+      return html
+    }
+  }
+
+  function convert(block) {
+    if (cache.has(block)) {
+      return cache.get(block)
+    }
+
+    // eslint-disable-next-line no-unused-vars
+    const [_, method, argString] = block.match(/<%= *(\w+)[ (]([^)]+)\)? *%>/)
+    const parts = argString.split(/, */)
+    const args = []
+    const kwargs = {}
+    let match
+    for (const part of parts) {
+      if ((match = part.match(/^:(.+) => (.+)$/))) {
+        kwargs[unquote(match[1])] = unquote(match[2])
+      } else if ((match = part.match(/^(.+): (.+)$/))) {
+        kwargs[unquote(match[1])] = unquote(match[2])
+      } else {
+        args.push(unquote(part))
+      }
+    }
+
+    if (typeof methods[method] === 'function') {
+      let output = methods[method](args, kwargs)
+      console.warn(`converted: ${block} -> ${output}`)
+      const escaped = block.replace('<', '').replace('>', '')
+      output = `<!--${escaped}-->\n${output}`
+      cache.set(block, output)
+      return output
+    } else {
+      console.warn(`No such ERB method implemented: "${method}"`)
+      return block
+    }
+  }
+}
+
+function replaceAll(str, input, output) {
+  return str.split(input).join(output)
+}
+
+function unquote(str) {
+  return str.replace(/^\s*"([^"]+)"\s*$/, (_, value) => value)
+}

lib/mdx-loader.js

@@ -1,11 +1,13 @@
 const {getOptions} = require('loader-utils')
 const mdx = require('@mdx-js/mdx')
+const octicons = require('@primer/octicons')
 
 const emoji = require('remark-emoji')
 const images = require('remark-images')
 const rehypePrism = require('./rehype-prism')
 const textr = require('remark-textr')
 const toc = require('remark-toc')
+const erbToHTML = require('./erb-to-html')
 
 const mdxExportJSONByDefault = require('mdx-constant')
 const grayMatter = require('gray-matter')
@@ -22,7 +24,30 @@ module.exports = async function(source) {
         [toc, {heading: '(table of|section)? contents'}],
         images,
         emoji,
-        [textr, {plugins: [typographicBase]}]
+        [textr, {plugins: [typographicBase]}],
+        [
+          erbToHTML,
+          {
+            methods: {
+              octicon: ([icon], attrs) => {
+                if (octicons[icon]) {
+                  return octicons[icon].toSVG(attrs)
+                } else {
+                  throw new Error(`No such octicon: "${icon}"`)
+                }
+              },
+              // eslint-disable-next-line camelcase
+              avatar_for: ([username, size], kwargs) => {
+                const name = username === 'current_user' ? 'github' : username
+                const attrs = Object.entries(kwargs)
+                  .map(([key, value]) => ` ${key}="${value}"`)
+                  .join(' ')
+                const s = size * 2
+                return `<img src="https://github.com/${name}.png?s=${s}" width="${size}" height="${size}"${attrs}>`
+              }
+            }
+          }
+        ]
       ],
       hastPlugins: [rehypePrism],
       compilers: [mdxExportJSONByDefault('frontMatter', data)]