feat(v2): Allow swizzling prism-include-languages in theme-classic (#2841)

* feat(v2): Allow swizzling prism-include-languages in theme-classic

* Add docs

* Improve docs

packages/docusaurus-theme-classic/src/prism-include-languages.js

@@ -6,21 +6,6 @@
  */
 
 import Prism from 'prism-react-renderer/prism';
-import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import prismIncludeLanguages from '@theme/prism-include-languages';
-import siteConfig from '@generated/docusaurus.config';
 
-(() => {
+prismIncludeLanguages(Prism);
-  if (ExecutionEnvironment.canUseDOM) {
-    const {
-      themeConfig: {prism: {additionalLanguages = []} = {}},
-    } = siteConfig;
-
-    window.Prism = Prism;
-
-    additionalLanguages.forEach((lang) => {
-      require(`prismjs/components/prism-${lang}`); // eslint-disable-line
-    });
-
-    delete window.Prism;
-  }
-})();

packages/docusaurus-theme-classic/src/theme/prism-include-languages.js

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import siteConfig from '@generated/docusaurus.config';
+
+const prismIncludeLanguages = (Prism) => {
+  if (ExecutionEnvironment.canUseDOM) {
+    const {
+      themeConfig: {prism: {additionalLanguages = []} = {}},
+    } = siteConfig;
+
+    window.Prism = Prism;
+
+    additionalLanguages.forEach((lang) => {
+      require(`prismjs/components/prism-${lang}`); // eslint-disable-line
+    });
+
+    delete window.Prism;
+  }
+};
+
+export default prismIncludeLanguages;

website/docs/markdown-features.mdx

@@ -538,6 +538,30 @@ module.exports = {
 };
 ```
 
+If you want to add highlighting for languages not yet supported by Prism, you can swizzle `prism-include-languages`:
+
+```bash npm2yarn
+yarn swizzle @docusaurus/theme-classic prism-include-languages
+```
+
+It will produce `prism-include-languages.js` in your `src/theme` folder. You can add highlighting support for custom languages by editing `prism-include-languages.js`:
+
+```js {8} title="src/theme/prism-include-languages.js"
+const prismIncludeLanguages = (Prism) => {
+    // ...
+
+    additionalLanguages.forEach((lang) => {
+      require(`prismjs/components/prism-${lang}`); // eslint-disable-line
+    });
+
+    require('/path/to/your/prism-language-definition');
+
+    // ...
+}
+```
+
+You can refer to [Prism's official language definitions](https://github.com/PrismJS/prism/tree/master/components) when you are writing your own language definitions.
+
 ### Line highlighting
 
 You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).