Docs enhancement - add a copy button to code examples

[shannonbux]

Summary

Code examples in tutorials, READme files, and guides could use a copy button so people don't miss a single thing when they copy code.

Motivation

When we did a Gatsby workshop a while ago, many workshop attendees' computer screens didn't show backtics very clearly and they missed copying them a lot.

Another related issue brought up by @twhiteaker is that when copying code from Firefox to VS code (and Notepad ++), the code ended up having two carriage returns added to the top and bottom. This actually mattered for a markdown file, it appears.

Acceptance criteria (by @marcysutton)

• As a keyboard user, I should be able to reach and operate a copy button for each code example and see a visible focus style.
• As a sighted user, I should see a graphic icon with adequate color contrast for each code example that is intuitive and clear that it will copy code to the clipboard.
  • If the icon button is unclear through user testing, adding the text “Copy” or “Copy to clipboard” may help
• As an assistive technology user, when navigating through the copy buttons I should hear unique button names like ${filename}: copy code to clipboard to know which file I’m copying to the clipboard.
• As a mouse user, clicking on the button should copy the adjacent code to the user’s clipboard in all major browsers.
• As a keyboard or screen reader user, focusing on the button and hitting the ENTER or SPACE keys should copy the adjacent code to the clipboard in all major browsers.
• As a sighted user, upon activating the button, I should see a visible “copied to clipboard!” toast notification.
• As a keyboard user, upon activating the copy button and toast notification, I should be able to hit the TAB key to reach a visible “Close” or “X” button with a visible focus style. When the toast notification is not visible, the button should be rendered inoperable.
• As a user with limited mobility or a cognitive impairment, I should have time to read the toast notification before it is dismissed by only closing it when activating the close button.
• As a sighted user, I should be able to dismiss the toast notification by clicking the close button or anywhere else on the screen.
• As a screen reader user, I should hear an announcement of ${filename} copied to clipboard after activating the button.
  • This can be accomplished with a persistent, visually hidden DOM element with ARIA `role=”status”.
  • Add and announce a keyboard shortcut, like “ENTER” to close? (We can play with it)

Potential icon:

Alternatively, there could be a button that just visually says "copy" without an icon.

[shannonbux]

@DSchau and @darpan I can do this! I'm assigning it to myself now. Thanks for doing the work, @DSchau !!! Edit from the future: Oh wait nope, this is not the file name issue. I can do that one.

[DSchau]

@shannonbux I didn't do the copy stuff yet! But you can definitely do the code title stuff if you're interested!

[shannonbux]

@fk can you add that reference you found to a copy button that you shared with @DSchau recently?

[DSchau]

This would be an awesome improvement for users browsing gatsby documentation.

I'm sure @fk has some ideas regarding design, but let's build it out functionally first and then we can augment that existing functionality with a sweet design.

I think it's a fair assumption that users of this plugin will also be users of gatsby-remark-prismjs, so I think we can build it as a gatsby-remark- plugin or built into gatsby-remark-prismjs itself. There are benefits to both approaches, so up for whatever whoever tackles this is leaning towards!

Further Detail

• This should enable a COPY button (or svg icon!), that when clicked, will copy the text of the snippet that the copy button refers to
• We should use the Clipboard API
  • I'm not super concerned about a fallback here--although that's always welcome--so let's consider this a progressively enhanced feature
  • Consider this copy-to-clipboard snippet
• The button probably needs some existing structure (e.g. HTML wrapper created with gatsby-remark-prismjs) so it might be a good idea to build it in at the plugin level, and enable this feature like so:

// gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        {
          resolve: `gatsby-remark-prismjs`,
          options: {
            copy: true
          }
        }
      ]
    }
  }
]

or an alternative approach is a standalone plugin that depends on the structure created by gatsby-remark-prismjs. I think that's more error prone, so I'd lean towards the former, but both are reasonable approaches.

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

there are pro's and con's to both approaches, so this should be a fun one to work on 💪

[felipecaputo]

I think I can help with this one

[DSchau]

@felipecaputo I can mark this as taken if you're interested! Let me know!

[felipecaputo]

That would be great. I'll take a look at the plugin tonight and get back to you

…

On Thu, Oct 4, 2018 at 4:31 PM Dustin Schau ***@***.***> wrote: @felipecaputo <https://github.com/felipecaputo> I can mark this as taken if you're interested! Let me know! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#5030 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AHZHGQDA9sqXglyvXVDEyWUM8MTkbJu5ks5uhmIKgaJpZM4TZRnC> .

[iamskok]

@marcysutton I currently don't have the capacity to test and implement accessibility features, but I will be more than happy to merge these PRs in gatsby-remark-code-buttons.

[alanonthegit]

@iamskok Does gatsby-remark-code-buttons work with gatsby-mdx as of now? I'm encountering these issues.

[iamskok]

@ar-stackrox it was never tested with gatsby-mdx . Can you please share a repo where I can reproduce this error?

[alanonthegit]

@iamskok I can't right now because the repo is private, but all I did was an npm install, and then add it to the gatsby-config / gatsby-remark-plugin like so -

[DSchau]

@ar-stackrox if at all possible--I'd request that you please re-open the issue in the package itself.

Thanks @iamskok for chiming in and being so helpful--we sincerely appreciate it!

[jmolivas]

@iamskok I can confirm the same issue when using MDX as reported by @ar-stackrox

[iamskok]

If anyone can reproduce this bug, please share it here

[marcysutton]

This component was spec'd as part of #14095 (currently needing to be prioritized amongst other work, so if anyone wants to pick this up that would be fine by us as long as it meets the requirements).

Here are some success criteria for what we need for this component to be successful:

Success criteria

• As a keyboard user, I should be able to reach and operate a copy button for each code example and see a visible focus style.
• As a sighted user, I should see a graphic icon with adequate color contrast for each code example that is intuitive and clear that it will copy code to the clipboard.
  • If the icon button is unclear through user testing, adding the text “Copy” or “Copy to clipboard” may help
• As an assistive technology user, when navigating through the copy buttons I should hear unique button names like ${filename}: copy code to clipboard to know which file I’m copying to the clipboard.
• As a mouse user, clicking on the button should copy the adjacent code to the user’s clipboard in all major browsers.
• As a keyboard or screen reader user, focusing on the button and hitting the ENTER or SPACE keys should copy the adjacent code to the clipboard in all major browsers.
• As a sighted user, upon activating the button, I should see a visible “copied to clipboard!” toast notification.
• As a keyboard user, upon activating the copy button and toast notification, I should be able to hit the TAB key to reach a visible “Close” or “X” button with a visible focus style. When the toast notification is not visible, the button should be rendered inoperable.
• As a user with limited mobility or a cognitive impairment, I should have time to read the toast notification before it is dismissed by only closing it when activating the close button.
• As a sighted user, I should be able to dismiss the toast notification by clicking the close button or anywhere else on the screen.
• As a screen reader user, I should hear an announcement of ${filename} copied to clipboard after activating the button.
  • This can be accomplished with a persistent, visually hidden DOM element with ARIA `role=”status”.
  • Add and announce a keyboard shortcut, like “ENTER” to close? (We can play with it)

Potential icon:

Alternatively, there could be a button that just visually says "copy" without an icon.

[iamskok]

@marcysutton thanks for providing all the requirements. I can continue working on this issue, but I will need some guidelines with reproducing and fixing MDX compatibility bug. Do you know anyone who will be able to help me with it?

[gillkyle]

Hey @iamskok, I'm not sure I can provide a ton of help on debugging remark plugins as sub-plugins of gatsby-mdx, however after reading through this issue I'm wondering if a remark plugin is still the best way to go. That direction was encouraged when MDX wasn't really an option, then this was held off until MDX was merged in (adding the potential for this to just be a component) like @marcysutton's comment mentions:

This component was spec'd as part of #14095 (currently needing to be prioritized amongst other work...

This is a great use case for MDX, but maybe @DSchau has an opinion since it would probably require reworking packages like gatsby-remark-code-titles and gatsby-remark-prismjs (which are making those code blocks now) into a new component.

I think using the remark plugin is still a good possibility and I don't have the most context around this either.

[Blackglade]

This plugin seems to have conflicts with gatsby-remark-prismjs. I need to specify this plugin before the gatsby-remark-prismjs otherwise it won't render. Also the styling conflicts with remark as well. Any ETA on when this will be moved to an official plugin

[iamskok]

@Blackglade can you please provide more information on styling conflicts you are talking about?

Not sure about ETA, I’ll need help from someone who is familiar with MDX to make it work. We are also waiting for @DSchau recommendations, because he has a lot of context on this issue .

[Blackglade]

@iamskok So I have the following plugins listed under gatsby-transformer-remark in the following order:

• gatsby-remark-code-buttons
• gatsby-remark-autolink-headers
• gatsby-remark-prismjs
• gatsby-remark-images

Anytime I include gatsby-remark-code-buttons after prism-js. The icon just doesn't appear. and digging through the html, it doesn't seem as if the divs were even rendered. As for the styling issue, ignoring the black icon of the clipboard (which can be changed), it's off center. I am using the prism-okaidia theme btw

[iamskok]

@Blackglade please try this order:

{
  resolve: `gatsby-transformer-remark`,
  options: {
    plugins: [
      `gatsby-remark-code-buttons`,
      `gatsby-remark-code-titles`,
      `gatsby-remark-autolink-headers`,
      `gatsby-remark-prismjs`,
      `gatsby-remark-images`
    ]
  }
}

The working example of using all of these plugins together can be found in gatsby-dev-blog-starter.

gatsby-remark-code-buttons provides generic styles to make positioning and adding tooltips easier, but the developer is responsible for tweaking the button styles to match a syntax highlighting theme.

[KyleAMathews]

👍 to doing this — just saw someone again at a workshop run into an error with a graphql query because they didn’t copy the closing backtick.