feat(v2): add support specify new languages for Prism

[lex111]

Motivation

Resolve #1879 and close #2356 as our users have an interest in this feature, I think we need to add this.

Related issues on Canny:

• https://docusaurus.canny.io/admin/board/feature-requests/p/support-rust-syntax-highlighting
• https://docusaurus.canny.io/admin/board/feature-requests/p/expand-default-syntax-highlighting-language-support

Cons of the current implementation:

• Pollution of global space, I do not know how to avoid this, given the use of Prism React Renderer :(

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

1. Add themeConfig.prism.additionalLanguages array with any languages missing in Prism React Renderer (rust eg)
2. Add corresponding code block, eg for rust:

```rust
fn main() {
    // Statements here are executed when the compiled binary is called

    // Print text to the console
    println!("Hello World!");
}

3. Make sure that it syntax highlighting for the added code block works correctly.

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit 6f99c05

https://deploy-preview-2250--docusaurus-2.netlify.com

[yangshun]

Since this is just about importing more modules, can we add those lines to getClientModules() of packages/docusaurus-theme-classic/src/index.js? You have access to themeConfig there. That way we don't have to add any global variables at all.

I think checking whether the language exists on Prism.language is optional and shouldn't be a blocker to use this approach. The checking should be possible in packages/docusaurus-theme-classic/src/index.js as well.

[lex111]

That way we don't have to add any global variables at all.

This will not work, we need to change the global Prism object. We already have a “ready-made” object from prism-react-renderer dep and we need to “modify” it. If we want a better solution, then we need to fork prism-react-renderer, I guess...

I think checking whether the language exists on Prism.language is optional

This check is necessary so as not to included (require) languages that have already been loaded (required). If the language is not supported by Prism, an exception will be thrown if you had this in mind.

[yangshun]

This will not work, we need to change the global Prism object.

How are we modifying it in the code? Or is requiring the language module modifying it within?

[lex111]

No, I mean that we need an existing Prism object, that is, we can not do support any language without this global variable from prism-react-renderer.

[yangshun]

Can you add another client module that does the exposing of the Prism object?

[lex111]

But how? Do you want to import Prism globally before loading React? Is this possible in the current implementation?

UPD: Even if this is done, will it really work? https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/defaultProps.js#L10
We use the Highlight component, which gets its own Prism object. It is not clear to me how to exposing this object from the context of client module?

[lex111]

@yangshun please could you investigate if there is another good solution here so I can close this PR?

[yangshun]

I'll take a stab at this over the weekend (or the next :S)

[lex111]

That would be great, although I have no idea how to do it differently, unless to fork prism-react-renderer lib and somehow modify the Prism object 🤷‍♂️

[ark120202]

Here's is a small plugin that have worked for me:

/** @returns {import('@docusaurus/types').Plugin<any>} */
module.exports = ({
  siteConfig: { themeConfig: { prism: { additionalLanguages = [] } = {} } = {} },
}) => ({
  getClientModules: () => [
    require.resolve('./prism-expose'),
    ...additionalLanguages.map(lang => require.resolve(`prismjs/components/prism-${lang}`)),
    require.resolve('./prism-cleanup'),
  ],
});

// prism-expose.js
import Prism from 'prism-react-renderer/prism';

window.Prism = Prism;

// prism-cleanup.js
window.Prism = undefined;

[lex111]

@ark120202 thank you 👍 , this approach apparently meant @yangshun, but I misunderstood him, and was looking for a solution in a completely different direction. I can rework my PR in accordance with this solution.

[lex111]

@yangshun re-check it out please.

[ark120202]

I might be wrong, but if there's no some context replacement I'm missing, all files matching this query would be included in a bundle

[yangshun]

Yeah agreed, I think so too! One alternative is to generate a file in one of the plugin steps that generates the list of require() statements containing just the languages needed and have this file import it.

[yangshun]

LGTM, my main concern is the dynamic requires.

[lex111]

@yangshun I fixed all bugs, please review.

[yangshun]

This should be part of devDependencies right?

[yangshun]

Some comments on what it does and why it is necessary would be nice.

[bravo-kernel]

@lex111 wow, I think you have just solved one of the most important feature requests/blockers. Amazing job ❤️