New gatsby-remark-embed-snippet plug-in (#3012)

* Added gatsby-remark-embed-snippet * Renamed source folder * Removed superfluous backticks from syntax/tests * Cleaned up gatsby-remark-prismjs hack a little * Lint/format * Removed unnecessary escape character * Added support (and test) for Shell scripts * Added support for JSX comments and multi-line highlight * Added highlight-range support * Tweaked an inline comment * Added warning check for invalid range expressions * Added spyOn to eslint globals
gatsbyjs · Nov 28, 2017 · 3c3fbcf · 3c3fbcf
1 parent e5a878b
commit 3c3fbcf
Show file tree

Hide file tree

Showing 9 changed files with 2,183 additions and 0 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -22,6 +22,9 @@
     "node": true,
     "jest": true
   },
+  "globals": {
+    "spyOn": true
+  },
   "rules": {
     "no-console": "off",
     "valid-jsdoc": "off",

diff --git a/packages/gatsby-remark-embed-snippet/.babelrc b/packages/gatsby-remark-embed-snippet/.babelrc
@@ -0,0 +1,5 @@
+{
+  "presets": [
+    ["../../.babelrc.js", { "browser": true }]
+  ]
+}
diff --git a/packages/gatsby-remark-embed-snippet/.gitignore b/packages/gatsby-remark-embed-snippet/.gitignore
@@ -0,0 +1 @@
+/index.js
diff --git a/packages/gatsby-remark-embed-snippet/.npmignore b/packages/gatsby-remark-embed-snippet/.npmignore
@@ -0,0 +1,34 @@
+# Logs
+logs
+*.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directory
+# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
+node_modules
+*.un~
+yarn.lock
+src
+flow-typed
+coverage
+decls
+examples
diff --git a/packages/gatsby-remark-embed-snippet/README.md b/packages/gatsby-remark-embed-snippet/README.md
@@ -0,0 +1,128 @@
+# gatsby-remark-embed-snippet
+
+Embeds the contents of specified files within Prism-formatted HTML blocks.
+
+## Overview
+
+### Embedding Files
+
+For example, given the following project directory structure:
+```
+./examples/
+├── sample-javascript-file.js
+├── sample-html-file.html
+```
+
+The following markdown syntax could be used to embed the contents of these files:
+```md
+# Sample JavaScript
+`embed:sample-javascript-file.js`
+
+# Sample HTML
+`embed:sample-html-file.html`
+```
+
+The resulting HTML for the above markdown would look something like this:
+```html
+<h1>Sample JavaScript</h1>
+<div class="gatsby-highlight">
+  <pre class="language-jsx">
+    <code>
+      <!-- Embedded content here ... -->
+    </code>
+  </pre>
+</div>
+
+<h1>Sample HTML</h1>
+<div class="gatsby-highlight">
+  <pre class="language-html">
+    <code>
+      <!-- Embedded content here ... -->
+    </code>
+  </pre>
+</div>
+```
+
+### Highlighting Lines
+
+You can also specify specific lines for Prism to highlight using `highlight-line` and `highlight-next-line` comments. You can also specify a range of lines to highlight, relative to a `highlight-range` comment.
+
+#### JavaScript example
+```js
+import React from 'react';
+import ReactDOM from 'react-dom';
+
+const name = "Brian"; // highlight-line
+
+ReactDOM.render(
+  <div>
+    {/* highlight-range{1-3} */}
+    <h1>
+      Hello, ${name}!
+    </h1>
+  </div>,
+  document.getElementById('root')
+);
+```
+
+#### CSS example
+```css
+html {
+  /* highlight-range{1-2} */
+  height: 100%;
+  width: 100%;
+}
+
+* {
+  box-sizing: border-box; /* highlight-line */
+}
+```
+
+#### HTML example
+```html
+<html>
+  <body>
+    <h1>highlight me</h1> <!-- highlight-line -->
+    <p>
+      <!-- highlight-next-line -->
+      And me
+    </p>
+  </body>
+</html>
+```
+
+#### YAML example
+```yaml
+foo: "highlighted" # highlight-line
+bar: "not highlighted"
+# highlight-range{1-2}
+baz: "highlighted"
+quz: "highlighted"
+```
+
+## Installation
+
+`npm install --save gatsby-remark-embed-snippet`
+
+## Usage
+
+```javascript
+// In your gatsby-config.js
+{
+  resolve: 'gatsby-remark-embed-snippet',
+  options: {
+    // Class prefix for <pre> tags containing syntax highlighting;
+    // defaults to 'language-' (eg <pre class="language-js">).
+    // If your site loads Prism into the browser at runtime,
+    // (eg for use with libraries like react-live),
+    // you may use this to prevent Prism from re-processing syntax.
+    // This is an uncommon use-case though;
+    // If you're unsure, it's best to use the default value.
+    classPrefix: 'language-',
+
+    // Example code links are relative to this dir.
+    // eg examples/path/to/file.js
+    directory: `${__dirname}/examples/`,
+  },
+},
+```
diff --git a/packages/gatsby-remark-embed-snippet/package.json b/packages/gatsby-remark-embed-snippet/package.json
@@ -0,0 +1,30 @@
+{
+  "name": "gatsby-remark-embed-snippet",
+  "description": "Gatsby plugin to embed formatted code snippets within markdown",
+  "version": "1.0.0",
+  "author": "Brian Vaughn <brian.david.vaughn@gmail.com>",
+  "dependencies": {
+    "babel-runtime": "^6.26.0",
+    "gatsby-remark-prismjs": "^1.2.9",
+    "normalize-path": "^2.1.1",
+    "parse-numeric-range": "^0.0.2",
+    "unist-util-map": "^1.0.3"
+  },
+  "devDependencies": {
+    "babel-cli": "^6.26.0",
+    "cross-env": "^5.0.5"
+  },
+  "keywords": [
+    "gatsby",
+    "gatsby-plugin",
+    "remark",
+    "prism"
+  ],
+  "license": "MIT",
+  "main": "index.js",
+  "scripts": {
+    "build": "babel src --out-dir . --ignore __tests__",
+    "watch": "babel -w src --out-dir . --ignore __tests__",
+    "prepublish": "cross-env NODE_ENV=production npm run build"
+  }
+}