Trouble with adding Scala language for syntax highligh

[majk-p]

🐛 Bug Report

Following the documentation (specifically https://docusaurus.io/docs/next/markdown-features/code-blocks#syntax-highlighting) I cannot simply add Scala syntax highlight by setting additionalLanguages: ['scala'].

Have you read the Contributing Guidelines on issues?

Yes

To Reproduce

Example repository: https://github.com/majk-p/docusaurus-syntax-highlight-issue
Reproduction in sandbox: https://codesandbox.io/s/wandering-cache-lzcj2?file=/docusaurus.config.js (affected resulting website: https://lzcj2.sse.codesandbox.io/docs/intro)

If possible, use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.

1. Initialize docusaurus npx @docusaurus/init@2.0.0-beta.0 init website classic
2. Add a snippet in a language that's not supported out of the box (as in https://docusaurus.io/docs/next/markdown-features/code-blocks#syntax-highlighting) for example: https://github.com/majk-p/docusaurus-syntax-highlight-issue/blob/master/website/docs/intro.md
3. Extend themeConfig.prism.additionalLanguages with the languages you have used in intro.md, e.g. additionalLanguages: ['scala'],

Please note that I've used Scala as my main sample, but this seems to also affects other languages e.g php

Expected behavior

1. The site renders correctly
2. The snippets are rendered with correct syntax highlight

Actual Behavior

When visiting the site (in the example the intro page) it renders blank. Additionally there's an issue in dev tools:

Your Environment

• Public source code: https://github.com/majk-p/docusaurus-syntax-highlight-issue

• Public site url: not published, please see reproducible demo below

• Docusaurus version used: 2.0.0-beta.0

• Environment name and version (e.g. Chrome 78.0.3904.108, Node.js 10.17.0):

• Browsers tested: 88.0.1 and Chromium 90.0.4430.212 (Official Build) snap (64-bit)

• Node: v12.22.1 locally and (I guess) v14 in sandbox (latest at the time of writing)

• Operating system and version (desktop or mobile): Ubuntu 20.04

Reproducible Demo

If possible, use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.
https://codesandbox.io/s/wandering-cache-lzcj2

Extra notes

Specifically for Scala snippets, using:

additionalLanguages: ['java', 'scala'],

Resolves the issue.

[nam-hle]

I restart the server and it works well. Maybe it's from the cache mechanism

[slorber]

I'm not sure exactly why this sandbox does not work, but I can make Scala work on the Docusaurus site:

    prism: {
      theme: require('prism-react-renderer/themes/github'),
      darkTheme: require('prism-react-renderer/themes/dracula'),
      additionalLanguages: ['scala'],
    },

    ```scala title="my-scala-code"
    class Main {
      lazy val toto = 23
    }
    ```

Can you make a repro where I can see exactly what you try to change from the init template? (for example using 2 branches and a PR to easily inspect the diff?)

[majk-p]

@slorber sure, I can do this. In the meantime, have you perhaps checked https://github.com/majk-p/docusaurus-syntax-highlight-issue? The problem can be reproduced by:

• Cloning the master branch
• Navigating to ./website
• Launching npx docusaurus start

The website opens in your default browser and the main page is broken.

[nam-hle]

@majk-p The better is a repo with two commits, the origin when install the docusaurus, and the other is what you change. Or two branches like @slorber.

[majk-p]

Here's the reproducing PR: majk-p/docusaurus-syntax-highlight-issue#1

The vanilla-docusaurus branch has been created by dropping whole repo contents and running npx @docusaurus/init@2.0.0-beta.0 init website classic and nothing more. Then I've switched to scala-snippet, dropped most of intro.md contents to eliminate the possibility of some other snippets causing this issue, added Scala snippet and the page is broken.

The issue persists even after restarting the server.

[slorber]

I see.

It looks like the scala language requires the scala language as it extends it. You also need to include java (and restart your server) to make it work:

    prism: {
      additionalLanguages: ["java", "scala"],
    },

https://0oc1y.sse.codesandbox.io/docs/intro

https://codesandbox.io/s/laughing-bush-0oc1y?file=/docusaurus.config.js:428-493

Syntax highlighting is not too good but it looks like a theme issue, just try another one

[majk-p]

@slorber If you'll have a look at the original post, this is what I've mentioned in the extra notes

In my opinion this definitely do not close the issue. Neither the official documentation nor the issue in console suggest solution to the issue. On one hand, on stable Docusaurus v1 page we can see following banner

Where migrating to the second version has some basic issues like this one, with no clear solution in the docs. How do you imagine people migrating with a policy like this?
I don't mean to be rude, but please consider proposing actual solution rather than confirming a workaround with no further actions.

[slorber]

@majk-p sorry I didn't see your extra notes.

IMHO, this is a niche issue that affects a very limited number of users, for which there is a good-enough workaround for v1 sites that need to upgrade to v2.

Docusaurus has a very small team and it's impossible to allocate too many resources to solve a specific problem like this one, we have better problems to solve.

Where migrating to the second version has some basic issues like this one, with no clear solution in the docs. How do you imagine people migrating with a policy like this?

Many people migrate successfully and most sites are already on v2 today if you look at npm trends. And Github issues are made for that.

Both v1 and v2 have their own set of bugs, and it seems utopic to expect that we don't recommend an upgrade unless there is absolutely 0 issue in the new version.

I don't mean to be rude, but please consider proposing actual solution rather than confirming a workaround with no further actions.

My proposed solution is to use the good-enough workaround. This is open-source, you are able to propose a better solution if you find one.

I can't dedicate many hours of my limited time to solve a problem that was reported once by a user that does not want to use the workaround. Eventually, we could keep it open and work on it but in a long time, or change the priority if a lot of Scala users complain about it.

I believe this issue is caused by an optimization we made to reduce the bundle size, ensuring we don't ship prism languages that end up being unused:

    configureWebpack() {
      const prismLanguages = additionalLanguages
        .map((lang) => `prism-${lang}`)
        .join('|');

      return {
        plugins: [
          new ContextReplacementPlugin(
            /prismjs[\\/]components$/,
            new RegExp(`^./(${prismLanguages})$`),
          ),
        ],
      };
    },

I don't feel we should remove this optimization just to solve this very specific problem, and I don't know how to refactor this optimization so that java is included by default whenever you add scala

In my opinion, you could also report this bug to prism itself, as they are using a proprietary extend system at runtime instead of relying on ESM/CJS imports, making it harder for bundlers to understand the dependency graph (ie that scala requires java)

Prism.languages.scala = Prism.languages.extend('java', {

If you feel that we should document this, docs PR are welcome