Skip to content

Commit dd64695

Browse files
kimbaudiwardpeet
kimbaudi
and
wardpeet
committed
feat(gatsby-remark-embed-snippet): allow relative embeds (#17339)
* feat(gatsby-remark-embed-snippet) allow embedding snippets relative to markdown * remove comments * update obsolete snapshot * update code based on code review * update gatsby-remark-embed-snippet README * undo code review changes * redo code review changes * update README based on code review * Reverted javascript=title doesn't work in README * remove unnecessary code * Update packages/gatsby-remark-embed-snippet/README.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update packages/gatsby-remark-embed-snippet/README.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update packages/gatsby-remark-embed-snippet/README.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update packages/gatsby-remark-embed-snippet/README.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update packages/gatsby-remark-embed-snippet/README.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update packages/gatsby-remark-embed-snippet/README.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update packages/gatsby-remark-embed-snippet/README.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update packages/gatsby-remark-embed-snippet/README.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update packages/gatsby-remark-embed-snippet/README.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update packages/gatsby-remark-embed-snippet/README.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * Update packages/gatsby-remark-embed-snippet/README.md Co-Authored-By: Marcy Sutton <marcy@gatsbyjs.com> * remove yarn instructions for consistency * fix highlight-line * fix highlight-line * fix highlight-line * fix highlight-line * fix highlight-line * fix highlight-line * fix highlight-line * fix highlight-line * fix highlight-line * fix highlight-line * fix highlight-line * minor change * undo minor change * prettier ignore file * fix prettier ignore Co-authored-by: Ward Peeters <ward@coding-tech.com>
1 parent 4af8a59 commit dd64695

File tree

4 files changed

+170
-115
lines changed

4 files changed

+170
-115
lines changed

‎packages/gatsby-remark-embed-snippet/README.md‎

Lines changed: 156 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,111 @@
11
# gatsby-remark-embed-snippet
22

3-
Embeds the contents of specified files within Prism-formatted HTML blocks.
3+
Embeds the contents of specified files as code snippets.
44

5-
## Overview
5+
## Installation
6+
7+
**Note**: This plugin depends on [gatsby-remark-prismjs](https://www.gatsbyjs.org/packages/gatsby-remark-prismjs/) and [gatsby-transformer-remark](https://www.gatsbyjs.org/packages/gatsby-transformer-remark/) plugins
8+
9+
```shell
10+
npm install --save gatsby-remark-embed-snippet gatsby-remark-prismjs gatsby-transformer-remark
11+
```
12+
13+
## Configuration
614

7-
### Embedding Files
15+
> **Important**: _You must add `gatsby-remark-embed-snippet` before `gatsby-remark-prismjs` in your plugins array!_
16+
> Otherwise, this plugin will not work because the code snippet files first need to be inlined before they can be transformed into code blocks.
17+
> For more information, see [gatsby-remark-prismjs](https://www.gatsbyjs.org/packages/gatsby-remark-prismjs/).
818
9-
For example, given the following project directory structure:
19+
To use `gatsby-remark-embed-snippet` plugin:
1020

21+
```js
22+
// gatsby-config.js
23+
module.exports = {
24+
plugins: [
25+
{
26+
resolve: `gatsby-transformer-remark`,
27+
options: {
28+
plugins: [
29+
{
30+
resolve: `gatsby-remark-embed-snippet`,
31+
options: {},
32+
},
33+
{
34+
resolve: `gatsby-remark-prismjs`,
35+
options: {},
36+
},
37+
],
38+
},
39+
},
40+
],
41+
}
1142
```
12-
./examples/
13-
├── sample-javascript-file.js
14-
├── sample-html-file.html
43+
44+
## Plugin option
45+
46+
| option | description |
47+
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
48+
| `directory` | Specify the directory where the code snippet files are located. If this option is omitted, this plugin will look for the code snippet files in the same directory as the markdown file. |
49+
50+
### Example 1: Specify that code snippet files are under the root directory
51+
52+
```js
53+
// In gatsby-config.js
54+
{
55+
resolve: `gatsby-remark-embed-snippet`,
56+
options: {
57+
directory: `${__dirname}`
58+
}
59+
},
60+
```
61+
62+
### Example 2: Specify that code snippet files are under a directory called `snippets`
63+
64+
```js
65+
// In gatsby-config.js
66+
{
67+
resolve: `gatsby-remark-embed-snippet`,
68+
options: {
69+
directory: `${__dirname}/snippets/`
70+
}
71+
},
72+
```
73+
74+
## Sample Usage I
75+
76+
Suppose you have the following file/folder structure and you want to embed `javascript-code.js` and `html-code.html` files as code snippets inside the Markdown file `index.md`.
77+
78+
```none
79+
.
80+
├── content
81+
│   └── my-first-post
82+
│      ├── index.md
83+
│      ├── javascript-code.js
84+
│      └── html-code.html
1585
```
1686

17-
The following markdown syntax could be used to embed the contents of these
18-
files:
87+
Add the following syntax to the Markdown file `index.md` to embed `javascript-code.js` and `html-code.html` as code snippets:
88+
89+
**`index.md`:**
1990

2091
```md
2192
# Sample JavaScript
2293

23-
`embed:sample-javascript-file.js`
94+
`embed:javascript-code.js`
2495

2596
# Sample HTML
2697

27-
`embed:sample-html-file.html`
98+
`embed:html-code.html`
2899
```
29100

30-
The resulting HTML for the above markdown would look something like this:
101+
The resulting HTML generated from the Markdown file above would look something like this:
31102

32103
```html
33104
<h1>Sample JavaScript</h1>
34105
<div class="gatsby-highlight">
35106
<pre class="language-jsx">
36107
<code>
37-
<!-- Embedded content here ... -->
108+
<!-- Embedded javascript-code.js content here ... -->
38109
</code>
39110
</pre>
40111
</div>
@@ -43,19 +114,82 @@ The resulting HTML for the above markdown would look something like this:
43114
<div class="gatsby-highlight">
44115
<pre class="language-html">
45116
<code>
46-
<!-- Embedded content here ... -->
117+
<!-- Embedded html-code.html content here ... -->
118+
</code>
119+
</pre>
120+
</div>
121+
```
122+
123+
## Sample Usage II
124+
125+
Suppose you have the following file/folder structure and you want to embed `javascript-code.js` and `html-code.html` files as code snippets inside the Markdown file `my-first-post.md`.
126+
127+
```none
128+
.
129+
├── content
130+
│   └── my-first-post.md
131+
├── snippets
132+
│   ├── javascript-code.js
133+
│   └── html-code.html
134+
```
135+
136+
Use `directory` plugin option to tell `gatsby-remark-embed-snippet` plugin that code snippet files are located under a directory called `snippets`:
137+
138+
```js
139+
// gatsby-config.js
140+
{
141+
resolve: `gatsby-remark-embed-snippet`,
142+
options: {
143+
directory: `${__dirname}/snippets/`,
144+
},
145+
},
146+
```
147+
148+
Add the following syntax to the Markdown file `my-first-post.md` to embed `javascript-code.js` and `html-code.html` as code snippets:
149+
150+
**`my-first-post.md`:**
151+
152+
```md
153+
# Sample JavaScript 2
154+
155+
`embed:javascript-code.js`
156+
157+
# Sample HTML 2
158+
159+
`embed:html-code.html`
160+
```
161+
162+
The resulting HTML generated from the markdown file above would look something like this:
163+
164+
```html
165+
<h1>Sample JavaScript 2</h1>
166+
<div class="gatsby-highlight">
167+
<pre class="language-jsx">
168+
<code>
169+
<!-- Embedded javascript-code.js content here ... -->
170+
</code>
171+
</pre>
172+
</div>
173+
174+
<h1>Sample HTML 2</h1>
175+
<div class="gatsby-highlight">
176+
<pre class="language-html">
177+
<code>
178+
<!-- Embedded html-code.html content here ... -->
47179
</code>
48180
</pre>
49181
</div>
50182
```
51183

184+
## Code snippet syntax highlighting
185+
52186
### Highlighting Lines
53187

54188
You can also specify specific lines for Prism to highlight using
55189
`highlight-line` and `highlight-next-line` comments. You can also specify a
56190
range of lines to highlight, relative to a `highlight-range` comment.
57191

58-
#### JavaScript example
192+
**JavaScript example**:
59193

60194
```js
61195
import React from "react"
@@ -72,7 +206,7 @@ ReactDOM.render(
72206
)
73207
```
74208

75-
#### CSS example
209+
**CSS example**:
76210

77211
```css
78212
html {
@@ -86,22 +220,23 @@ html {
86220
}
87221
```
88222

89-
#### HTML example
223+
**HTML example**:
90224

225+
<!-- prettier-ignore-start -->
91226
```html
92227
<html>
93228
<body>
94-
<h1>highlight me</h1>
95-
<!-- highlight-line -->
229+
<h1>highlight me</h1> <!-- highlight-line -->
96230
<p>
97231
<!-- highlight-next-line -->
98232
And me
99233
</p>
100234
</body>
101235
</html>
102236
```
237+
<!-- prettier-ignore-end -->
103238

104-
#### YAML example
239+
**YAML example**:
105240

106241
```yaml
107242
foo: "highlighted" # highlight-line
@@ -115,7 +250,7 @@ quz: "highlighted"
115250
116251
It's also possible to specify a range of lines to be hidden.
117252
118-
#### JavaScript example
253+
**JavaScript example**:
119254
120255
```js
121256
// hide-range{1-2}
@@ -157,74 +292,3 @@ function App() {
157292
)
158293
}
159294
```
160-
161-
## Installation
162-
163-
`npm install --save gatsby-remark-embed-snippet`
164-
165-
## How to use
166-
167-
**Important**: This module must appear before `gatsby-remark-prismjs` in your
168-
plugins array, or the markup will have already been transformed into a code
169-
block and this plugin will fail to detect it and inline the file.
170-
For further information about its options, visit the `gatsby-remark-prismjs`
171-
[README](https://www.gatsbyjs.org/packages/gatsby-remark-prismjs/).
172-
173-
```js
174-
// In your gatsby-config.js
175-
module.exports = {
176-
plugins: [
177-
{
178-
resolve: `gatsby-transformer-remark`,
179-
options: {
180-
plugins: [
181-
{
182-
resolve: "gatsby-remark-embed-snippet",
183-
options: {
184-
// Example code links are relative to this dir.
185-
// eg examples/path/to/file.js
186-
directory: `${__dirname}/examples/`,
187-
},
188-
},
189-
{
190-
resolve: `gatsby-remark-prismjs`,
191-
options: {
192-
// Class prefix for <pre> tags containing syntax highlighting;
193-
// defaults to 'language-' (eg <pre class="language-js">).
194-
// If your site loads Prism into the browser at runtime,
195-
// (eg for use with libraries like react-live),
196-
// you may use this to prevent Prism from re-processing syntax.
197-
// This is an uncommon use-case though;
198-
// If you're unsure, it's best to use the default value.
199-
classPrefix: "language-",
200-
// This is used to allow setting a language for inline code
201-
// (i.e. single backticks) by creating a separator.
202-
// This separator is a string and will do no white-space
203-
// stripping.
204-
// A suggested value for English speakers is the non-ascii
205-
// character '›'.
206-
inlineCodeMarker: null,
207-
// This lets you set up language aliases. For example,
208-
// setting this to '{ sh: "bash" }' will let you use
209-
// the language "sh" which will highlight using the
210-
// bash highlighter.
211-
aliases: {},
212-
// This toggles the display of line numbers globally alongside the code.
213-
// To use it, add the following line in gatsby-browser.js
214-
// right after importing the prism color scheme:
215-
// `require("prismjs/plugins/line-numbers/prism-line-numbers.css");`
216-
// Defaults to false.
217-
// If you wish to only show line numbers on certain code blocks,
218-
// leave false and use the {numberLines: true} syntax.
219-
showLineNumbers: false,
220-
// If setting this to true, the parser won't handle and highlight inline
221-
// code used in markdown i.e. single backtick code like `this`.
222-
noInlineHighlight: false,
223-
},
224-
},
225-
],
226-
},
227-
},
228-
],
229-
}
230-
```

‎packages/gatsby-remark-embed-snippet/src/__tests__/__snapshots__/index.js.snap‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -448,6 +448,8 @@ Object {
448448
}
449449
`;
450450

451+
exports[`gatsby-remark-embed-snippet should not error if missing optional config options 1`] = `[Function]`;
452+
451453
exports[`gatsby-remark-embed-snippet should not modify non-embed inlineCode nodes 1`] = `
452454
Object {
453455
"children": Array [

‎packages/gatsby-remark-embed-snippet/src/__tests__/index.js‎

Lines changed: 2 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,10 @@ describe(`gatsby-remark-embed-snippet`, () => {
2020
fs.readFileSync.mockReturnValue(`const foo = "bar";`)
2121
})
2222

23-
it(`should error if missing required config options`, () => {
23+
it(`should not error if missing optional config options`, () => {
2424
const markdownAST = remark.parse(`\`embed:hello-world.js\``)
2525

26-
expect(() => plugin({ markdownAST })).toThrow(
27-
`Required option "directory" not specified`
28-
)
26+
expect(() => plugin({ markdownAST })).toMatchSnapshot()
2927
})
3028

3129
it(`should error if the specified directory does not exist`, () => {
@@ -48,16 +46,6 @@ describe(`gatsby-remark-embed-snippet`, () => {
4846
)
4947
})
5048

51-
it(`should error if an invalid file path is specified`, () => {
52-
fs.existsSync.mockImplementation(path => path !== `examples/hello-world.js`)
53-
54-
const markdownAST = remark.parse(`\`embed:hello-world.js\``)
55-
56-
expect(() => plugin({ markdownAST }, { directory: `examples` })).toThrow(
57-
`Invalid snippet specified; no such file "examples/hello-world.js"`
58-
)
59-
})
60-
6149
it(`should not modify non-embed inlineCode nodes`, () => {
6250
const markdownAST = remark.parse(`\`console.log("hi")\``)
6351
const transformed = plugin({ markdownAST }, { directory: `examples` })

0 commit comments

Comments
 (0)