Add a copy button to markdown code snippets in Gatsby sites with compatibility for MDX and use of the browser Clipboard API.
This package and implementation is discussed in this blog post.
yarn add @jpfulton/gatsby-remark-copy-button
Add the configuration entry to your gatsby-config.js
file. This plugin
must be added before other plugins that operate on code
nodes and
markdown code snippets to operate correctly.
The following listing assumes you are using the gatsby-plugin-mdx
plugin.
However, this plugin may also be used with the gatsby-transformer-remark
plugin.
plugins: [
{
resolve: `gatsby-plugin-mdx`,
options: {
extensions: [`.mdx`, `.md`],
gatsbyRemarkPlugins: [
{
resolve: `@jpfulton/gatsby-remark-copy-button`,
},
{
resolve: `gatsby-remark-code-titles`,
},
{
resolve: `gatsby-remark-prismjs`,
},
],
},
},
],
All plugin options are optional. However, it is strongly suggested that you customize them to override styling to fit your site's look, feel and layout.
{
resolve: `@jpfulton/gatsby-remark-copy-button`,
options: {
// Provide a text label for the copy button.
// Default: null
buttonText: null,
// Provide a complete SVG tag string to replace the default
// copy icon. Be sure to include a class of "copy-icon" on your custom
// SVG tag when using this option.
copySvg: null,
// Provide a complete SVG tag string to replace the default
// success icon. Be sure to include a class of "success-icon" on your custom
// SVG tag when using this option.
successSvg: null,
// Provide a custom container class for the <div> tag that contains
// the copy button to apply custom styling.
// Default: "gatsby-remark-copy-button-container"
customButtonContainerClass: null,
// Provide a custom button class for the copy button to apply
// custom styling.
// Default: "gatsby-remark-copy-button"
customButtonClass: null,
},
},
Custom styling may be applied to the default classes or using the options above custom classes may be applied to the injected markup.
.gatsby-remark-copy-button-container {
}
.gatsby-remark-copy-button {
}
Apply custom styles by adding a style sheet to your gatsby-browser.js
file.
// gatsby-browser.js
import "./src/styles/copy-button.scss";
When enabled on code snippet, the following HTML
will be injected into
the output of the page after parsing the Markdown AST using the default
plugin options. It will be injected above the code snippet in the
generated HTML
.
<div class="gatsby-remark-copy-button-container">
<button
class="gatsby-remark-copy-button"
onclick="copyToClipboard(`CLEANED CODE CONTENT TO COPY HERE`, this)"
>
<svg
class="copy-icon"
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
>
...
</svg>
<svg
class="success-icon"
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
>
...
</svg>
</button>
</div>
Once installed, the copy button may optionally be enabled by adding
to the code snippet declaration within markdown files. When this plugin
is used in conjunction with the gatsby-remark-prismjs
plugin, the
{clipboardButton: true}
option may be provided in any order with other
prismjs options.
```js {clipboardButton: true}
const example = "This content will end up on the user's clipboard";
```
For details on contributing to this project, reference both the CONTRIBUTING.md and CODE_OF_CONDUCT.md documentation.
To submit a bug or feature request, please open an issue here.
To report create a security advisory, please reference the SECURITY.md policy document.