[gatsby-remark-prismjs] allow adding PrismJS plugins

[muuvmuuv]

Summary

PrismJS has great plugins that I would like to use, e.g.:

• https://prismjs.com/plugins/copy-to-clipboard/
• https://prismjs.com/plugins/show-invisibles/
• https://prismjs.com/plugins/show-language/

I'm not sure if this is already possible but couldn't find any reference in the docs. Would be pretty great to allow passing plugins.

Basic example

const gatsbyPrism =  {
    resolve: `gatsby-remark-prismjs`,
    options: {
      noInlineHighlight: true,
      prompt: {
        user: 'root',
        host: 'localhost',
        global: false,
      },
      plugins: [
        require.resolve(
          'prismjs/plugins/show-invisibles/prism-show-invisibles'
        ),
      ],
    },
  }

Motivation

This would allow me to have the same awesome code highlighter as the Gatsby docs themselves.

[blainekasten]

@muuvmuuv I don't think we have a generic way to use plugins with prismjs yet. I am pretty confident we would happily accept a PR to do exactly what you outlined above. Interested in submitting a PR to do this?

[muuvmuuv]

I'd love to if I would have time, I'm pretty in hurry to get my portfolio done to apply for a new job, so not much time for OSS right now. It was just something I noticed while polishing everything up. Hopefully someone else will have the same issue and more time than me :)

[blainekasten]

@muuvmuuv Totally understand! Hopefully someone comes along and want's to jump in! If anyone wants to, ping here and I'd be more than happy to point you in the right direction!

[acagastya]

@blainekasten I was wondering how Gatsby's website is able to display language and copy to clipboard feature as seen in the photo below.

[davidbelow]

Hello @muuvmuuv ! Do you mean that gatsby-remark-prismjs should be able to consume other PrismJS plugins? Ad hoc seems to me that the plugins you want:

• https://prismjs.com/plugins/copy-to-clipboard/
• https://prismjs.com/plugins/show-invisibles/
• https://prismjs.com/plugins/show-language/

Should be wrapped for the Gatsby plugin system. Resulting in something like this:

• gatsby-remark-prismjs-copy-to-clipboard
• gatsby-remark-prismjs-show-invisibles
• gatsby-remark-prismjs-show-language

Are my suppositions correct?

[LekoArts]

I was wondering how Gatsby's website is able to display language and copy to clipboard feature as seen in the photo below.

A custom code block for MDX and some CSS: https://github.com/gatsbyjs/gatsby/blob/master/www/src/components/code-block/index.js
https://github.com/gatsbyjs/gatsby/blob/master/www/src/utils/styles/global.js

Are my suppositions correct?

Wrapping them in respective plugins would be the easier thing to do, yes.

[muuvmuuv]

Sounds good to wrap them in Gatsby plugins! The plugins that are included in gatsby-remark-prismjs (line-highlight, line-numbers and prompts) could then be removed and added to the list, to make it consistent.

[davidbelow]

Ok, so it sounds for me that at the end we're going to have six new plugins.

Three completely new plugins:

• gatsby-prismjs-copy-to-clipboard
• gatsby-prismjs-show-invisibles
• gatsby-prismjs-show-language

Three extracted from gatsby-remark-prismjs and converted to Gatsby plugins:

• gatsby-prismjs-line-highlight
• gatsby-prismjs-line-numbers
• gatsby-prismjs-prompts

Questions:

• Is this the standard way to do it in Gatsby?
• For current users of the plugin, the extraction would be a breaking change. How you handle such cases?
• Could the current gatsby-remark-prismjs implementation handle the extraction of the current PrismJS plugins easily or it would need major changes?
• Could this develop into a "plugin hell"?

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        {
          resolve: `gatsby-remark-prismjs`,
          options: {
            plugins: [
              {
                resolve: `gatsby-prismjs-copy-to-clipboard`,
                options: {
// etc.

[blainekasten]

Hey @muuvmuuv, @rbelow !

I talked with @LekoArts, and has comment wasn't very clear.

Are my suppositions correct?

Wrapping them in respective plugins would be the easier thing to do, yes.

He was just implying that would be easier, but we agree that the right thing to do here is to just add an option for plugins which the user can supply. Take this for inspiration: https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-mdx/README.md#md-plugins

[davidbelow]

Thanks, @blainekasten . After looking to your link the solution would be something like this:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-remark-prismjs`,
      options: {
        prismjsPlugins: [
          require("prismjs/plugins/show-invisibles/prism-show-invisibles"),
          require("plugins/show-invisibles/prism-show-invisibles.js"),
          // etc.
        ],
      },
    },
  ],
}

More questions:

• From where comes "plugins/show-invisibles/prism-show-invisibles.js". It's available as npm package?
• In the prism-show-invisibles example there is this to see:

<section>
	<h1>Examples</h1>

	<pre data-src="plugins/show-invisibles/prism-show-invisibles.js"></pre>

	<pre data-src="plugins/show-invisibles/prism-show-invisibles.css"></pre>

	<pre data-src="plugins/show-invisibles/index.html"></pre>
</section>

This would mean that the prism-show-invisibles plugin needs to load CSS and HTML to work. Or I'm wrong?

• The prism-copy-to-clipboard plugin also depends on Clipboard.js. Would it be loaded for example in an additional require("node_modules/clipboard.js/2.0.0/clipboard.min.js")?
• On the PrismJS site, I only see an option to download PrismJS + plugins. Can I download from somewhere only the plugins?

It's nice to make gatsby-remark-prismjs extensible but it would be hard to maintain if the PrismJS plugin system does not offer the plugins separately. I suppose that the current implementation is this download: https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript&plugins=line-highlight+line-numbers + wrapper for the Gatsby plugin system.

What do you think?

[muuvmuuv]

@rbelow Because GatsbyJS uses webpack, I guess CSS can easily be imported somewhere in your browser config. So JS goes into prismjsPlugins and CSS into gatsby-browser.js.

Plugin dependencies will be required in prismjs so no need to handle this by yourself, I think webpack will bundle them.

Why do you want to download the plugins or anything manually? Just npm install prismjs and require them, like in your prismjsPlugins example would be enough.

[davidbelow]

Thanks, @muuvmuuv . I'll take a look and start today.

[davidbelow]

Is the proper way to test the plugin with npm link and a Gatsby starter project? Or is there a Gatsby way of plugin testing?

[blainekasten]

@rbelow im on my phone, so sorry for the short answer. But this doc should help you get a local dev setup

https://www.gatsbyjs.org/contributing/setting-up-your-local-dev-environment/

[acagastya]

@muuvmuuv In the gatsby-config.js, under gatsby-plugin-mdx, add gatsby-remark-prismjs in gatsbyRemarkPlugins and everything works fine.

See: https://github.com/acagastya/gatsby-test/blob/1f74adf91d6a9029c8a05dcafc04fefae0807400/gatsby-config.js#L50

[blainekasten]

Let's keep the scope of this issue to adding support for prism plugins to the gatsby-remark-prismjs 👍

[davidbelow]

Hi! I opened a WIP pull request.

The pull request adds the Prism Show Invisibles Plugin to gatsby-remark-prismjs. The original plugin is an IIFE and does not hook into the Prism environment variable of gatsby-remark-prismjs on build time (see also gatsby-remark-prismjs documentation). Maybe I'm missing something. The implementation is almost the original plugin file so maintenance is easy.

I think we can create a plugin system for gatsby-remark-prismjs with all original plugins with this method easily but maybe there is a better solution.

I'll add tests to the pull request and wait for your feedback @blainekasten , @acagastya , @muuvmuuv .

How we can proceed with the Gatsby documentation?

How we can proceed with the two other plugins?

• https://prismjs.com/plugins/copy-to-clipboard/
• https://prismjs.com/plugins/show-language/

[davidbelow]

@blainekasten , @muuvmuuv , @acagastya the pull request is now open. It would be glad to have your feedback.

I recommend to open two new issues for the two remaining plugins. Maybe also one for the "pluginization" of gatsby-remark-prismjs?

[muuvmuuv]

LGTM for now. Later this would need to be extended by a default plugin Class which defines how plugins should be invoked.

[davidbelow]

The PR is now merged, @muuvmuuv . How do you proceed normally with the documentation @blainekasten ? Should a new issue be opened for the documentation update or should it be done within the scope of this one?

When can this issue be closed (is there something like a definition of done)?

For the other two plugins you mentioned @muuvmuuv :

• https://prismjs.com/plugins/copy-to-clipboard/
• https://prismjs.com/plugins/show-language/

Is still a need for them? Do you want to open two new issues for them?

@muuvmuuv , @blainekasten , @acagastya , @LekoArts do you think there is a real need for a further "pluginization" of gatsby-remark-prismjs?

[mgrn0]

@rbelow I think there is indeed a need for the "copy to clipboard" plugin. Do you know if there was an additional issue created for that?

[muuvmuuv]

Hey @rbelow, not now. I have anyway coded it my own with prism-react-renderer which is more flexible together with gatsby-plugin-mdx but thank for the work. I still think that for other people this is important, to have the same experience with primjs in Gatsby than in vanilla.

https://github.com/muuvmuuv/portfolio/blob/master/src/components/Code.jsx

[manishsundriyal]

@blainekasten @LekoArts @rbelow
Similar to @rbelow 's PR for show-Invisibles, I was trying to add in the copy-to-clipboard plugin.
I am having issues to test it locally, I have gone through the official docs. It would be really helpful if there is anyone who can help me out.
Issue: The changes are not reflecting in the testing site, even though the node_modules>gatsby-remark-prismjs is updated.

Also, you can mark this comment as off-topic.

[davidbelow]

@manishsundriyal I have written an article explaining: how to set up your local environment. Please, contact me if something in the guide doesn't work as expected or it's hard to understand.

[TamimiGitHub]

Hey @rbelow ! I checkout out your PR that you merged earlier and was wondering would other plugins be added in the same way? So what I am referring to is the https://prismjs.com/plugins/copy-to-clipboard/ plugin. Your PR only added the show invisibles prism plugin, not sure if there is another issue involved with the copy-to-clipboard plugin. I, similar to @muuvmuuv, am wondering how to incorporate a copy to clipboard functionality to my code block snippet generated by the gatsby-remark-prismjs plugin.

Thanks!

[mgrn0]

any news on this? I also want to add clipboard functionality to code snippets and am stuck.

[TamimiGitHub]

Not sure if @rbelow has any input on this?