Skip to main content
Official Plugin
View plugin on GitHub
See starters using this

gatsby-remark-embed-snippet

Embeds the contents of specified files as code snippets.

Installation

Note: This plugin depends on gatsby-remark-prismjs and gatsby-transformer-remark plugins

npm install --save gatsby-remark-embed-snippet gatsby-remark-prismjs gatsby-transformer-remark

Configuration

Important: You must add gatsby-remark-embed-snippet before gatsby-remark-prismjs in your plugins array! Otherwise, this plugin will not work because the code snippet files first need to be inlined before they can be transformed into code blocks. For more information, see gatsby-remark-prismjs.

To use gatsby-remark-embed-snippet plugin:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: `gatsby-remark-embed-snippet`,
            options: {},
          },
          {
            resolve: `gatsby-remark-prismjs`,
            options: {},
          },
        ],
      },
    },
  ],
}

Plugin option

option description
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.

Example 1: Specify that code snippet files are under the root directory

// In gatsby-config.js
{
  resolve: `gatsby-remark-embed-snippet`,
  options: {
    directory: `${__dirname}`
  }
},

Example 2: Specify that code snippet files are under a directory called snippets

// In gatsby-config.js
{
  resolve: `gatsby-remark-embed-snippet`,
  options: {
    directory: `${__dirname}/snippets/`
  }
},

Sample Usage I

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.

.
β”œβ”€β”€ content
β”‚Β Β  └── my-first-post
β”‚Β Β   Β Β  β”œβ”€β”€ index.md
β”‚Β Β   Β Β  β”œβ”€β”€ javascript-code.js
β”‚Β Β   Β Β  └── html-code.html

Add the following syntax to the Markdown file index.md to embed javascript-code.js and html-code.html as code snippets:

index.md:

# Sample JavaScript

`embed:javascript-code.js`

# Sample HTML

`embed:html-code.html`

The resulting HTML generated from the Markdown file above would look something like this:

<h1>Sample JavaScript</h1>
<div class="gatsby-highlight">
  <pre class="language-jsx">
    <code>
      <!-- Embedded javascript-code.js content here ... -->
    </code>
  </pre>
</div>

<h1>Sample HTML</h1>
<div class="gatsby-highlight">
  <pre class="language-html">
    <code>
      <!-- Embedded html-code.html content here ... -->
    </code>
  </pre>
</div>

Sample Usage II

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.

.
β”œβ”€β”€ content
β”‚Β Β  └── my-first-post.md
β”œβ”€β”€ snippets
β”‚Β Β  β”œβ”€β”€ javascript-code.js
β”‚Β Β  └── html-code.html

Use directory plugin option to tell gatsby-remark-embed-snippet plugin that code snippet files are located under a directory called snippets:

// gatsby-config.js
{
  resolve: `gatsby-remark-embed-snippet`,
  options: {
    directory: `${__dirname}/snippets/`,
  },
},

Add the following syntax to the Markdown file my-first-post.md to embed javascript-code.js and html-code.html as code snippets:

my-first-post.md:

# Sample JavaScript 2

`embed:javascript-code.js`

# Sample HTML 2

`embed:html-code.html`

The resulting HTML generated from the markdown file above would look something like this:

<h1>Sample JavaScript 2</h1>
<div class="gatsby-highlight">
  <pre class="language-jsx">
    <code>
      <!-- Embedded javascript-code.js content here ... -->
    </code>
  </pre>
</div>

<h1>Sample HTML 2</h1>
<div class="gatsby-highlight">
  <pre class="language-html">
    <code>
      <!-- Embedded html-code.html content here ... -->
    </code>
  </pre>
</div>

Code snippet syntax highlighting

Highlighting Lines

You can 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:

import React from "react"
import ReactDOM from "react-dom"

const name = "Brian"
ReactDOM.render(
  <div>
    <h1>Hello, ${name}!</h1>  </div>,  document.getElementById("root"))

CSS example:

html {
  height: 100%;  width: 100%;}

* {
  box-sizing: border-box;}

HTML example:

<html>
  <body>
    <h1>highlight me</h1>    <p>
      And me    </p>
  </body>
</html>

YAML example:

foo: "highlighted"bar: "not highlighted"
baz: "highlighted"quz: "highlighted"

Hide Lines

It’s also possible to specify a range of lines to be hidden.

You can either specify line ranges in the embed using the syntax:

  • Lx - Embed one line from a file

  • Lx-y - Embed a range of lines from a file

  • Lx-y,a-b - Embed non-consecutive ranges of lines from a file

Markdown example:

This is the JSX of my app:

`embed:App.js#L6-8`

With this example snippet:

import React from "react"
import ReactDOM from "react-dom"

function App() {
  return (
    <div className="App">
      <h1>Hello world</h1>
    </div>
  )
}

Will produce something like this:

This is the JSX of my app:

    <div className="App">
      <h1>Hello world</h1>
    </div>

JavaScript example:

You can also add // hide-range comments to your files.


function App() {
  return (
    <div className="App">
      <ul>
        <li>Not hidden</li>
        <li>Not hidden</li>
      </ul>
    </div>
  )
}

Will produce something like this:

function App() {
  return (
    <div className="App">
      <ul>
        <li>Not hidden</li>
        <li>Not hidden</li>
      </ul>
    </div>
  )
}
Docs
Tutorials
Plugins
Blog
Showcase