Skip to content

Latest commit

 

History

History
139 lines (107 loc) · 4.6 KB

README.md

File metadata and controls

139 lines (107 loc) · 4.6 KB
Raw

highlightjs-copy

Netlify Status

A simple, accessible highlightjs plugin to add a copy button to your codeblocks.

Preview

Demo

Check out the demo

Install

Using a CDN

<script src="https://unpkg.com/highlightjs-copy/dist/highlightjs-copy.min.js"></script>
<link
  rel="stylesheet"
  href="https://unpkg.com/highlightjs-copy/dist/highlightjs-copy.min.css"
/>

NPM

npm install highlightjs-copy

Usage

Basic usage

hljs.addPlugin(new CopyButtonPlugin());

Autohide

By default, the copy button is hidden until a user hovers the code block. Set this to false to have the copy button always visible.

hljs.addPlugin(
  new CopyButtonPlugin({
    autohide: false, // Always show the copy button
  })
);

With a callback

hljs.addPlugin(
  new CopyButtonPlugin({
    callback: (text, el) => console.log("Copied to clipboard", text),
  })
);

Modify copied text with hooks

hljs.addPlugin(
  new CopyButtonPlugin({
    hook: (text, el) => text + "\nCopied from my cool website.",
  })
);

Advanced hook example

<!-- Code block example -->
<pre>
  <code class="language-bash" data-replace="{{YOUR_API_KEY}}" data-replaceWith="grtf32a35bbc...">
    gretel configure --key {{YOUR_API_KEY}}
  </code>
</pre>

<script>
  hljs.addPlugin(
    new CopyButtonPlugin({
      hook: (text, el) => {
        let { replace, replacewith } = el.dataset;
        if (replace && replacewith) {
          return text.replace(replace, replacewith);
        }
        return text;
      },
      callback: (text, el) => {
        /* logs `gretel configure --key grtf32a35bbc...` */
        console.log(text);
      },
    })
  );
  hljs.highlightAll();
</script>

Localization

highlightjs-copy supports multiple locales by providing the correct language for accessibility.

hljs.addPlugin(
  new CopyButtonPlugin({
    lang: "es", // The copy button now says "Copiado!" when selected.
  })
);

This option is unnecessary if you correctly add the lang attribute to your document. You can override this behavior by providing the lang option as described above.

<html lang="es">
  <body>
    <!-- The plugin language defaults to `es` to match the document, so manually setting it is unnecessary. -->
    <script>
      hljs.addPlugin(new CopyButtonPlugin());
    </script>
  </body>
</html>

If the document has no lang set and the lang option is not provided, it will default to en.

Customization

CSS selector Details
.hljs-copy-wrapper Applied to the parent <pre> element that wraps the .hljs code.
.hljs-copy-container A parent element to the button, in charge of absolute positioning and animating the button when hovering.
.hljs-copy-button The copy button itself.

The variables --hljs-theme-background and --hljs-theme-color are automatically applied to the parent element. This allows the button to inherit the code block's text and background colors.
[data-copied='true'] This data attribute is applied to the copy button and is set to true for two seconds when the copy action is performed.
.hljs-copy-alert A visually hidden status element that announces the copy confirmation to screen readers.