3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-08-03 00:39:45 +02:00
Code Issues Projects Releases Packages Wiki Activity

chore: upgrade rehype-katex with ESM support, update docs (#6320)

Browse source 
* chore: upgrade rehype-katex to latest version with ESM support and update the docs

* Update documentation to reflect ESM upgrade is currently optional

* rewording

* final tweaks

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
This commit is contained in:
Pranab Das 2022-01-14 09:06:10 +08:00 • committed by GitHub
parent afe7464306
commit 4ebb1ca8c8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 273 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

65
website/docs/guides/markdown-features/markdown-features-math-equations.mdx
View file

@ -127,3 +127,68 @@ module.exports = {
// highlight-end
};
```
## Upgrading rehype-katex beyond recommended version
:::tip
Only use the latest version if you actually need the bleeding-edge features of $\KaTeX$. Most users should find the older versions work just as well.
:::
The latest versions of `rehype-katex` (starting from `v6.0.0`) has moved to ES Modules, a new module system of JavaScript, which Docusaurus doesn't officially support yet. However, it is possible to import `rehype-katex` dynamically, using an async config creator. Docusaurus will call this creator function and wait for it to return the config object.
```js title="docusaurus.config.js"
async function createConfig() {
// ES Modules are imported with `import()` instead of `require()`, and are imported asynchronously
// highlight-next-line
const katex = (await import('rehype-katex')).default;
return {
// ...
};
}
```
In this case, the overall configuration changes will look like:
```js title="docusaurus.config.js"
// highlight-next-line
const math = require('remark-math');
async function createConfig() {
// highlight-next-line
const katex = (await import('rehype-katex')).default;
return {
title: 'Docusaurus',
tagline: 'Build optimized websites quickly, focus on your content',
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
path: 'docs',
// highlight-start
remarkPlugins: [math],
rehypePlugins: [katex],
// highlight-end
},
},
],
],
// highlight-start
stylesheets: [
{
href: 'https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css',
type: 'text/css',
integrity:
'sha384-MlJdn/WNKDGXveldHDdyRP1R4CTHr3FeuDNfhsLPYrq2t0UBkUdK2jyTnXPEK1NQ',
crossorigin: 'anonymous',
},
],
// highlight-end
};
return config;
}
module.exports = createConfig;
```

2
website/docs/guides/markdown-features/markdown-features-plugins.mdx
View file

@ -49,7 +49,7 @@ npm install --save remark-math@3 rehype-katex@4
:::note
There's recently a trend in the Remark/Rehype ecosystem to migrate to ES Modules, which Docusaurus doesn't support yet. Please make sure your installed plugin version is CommonJS-compatible before we officially support ESM.
There's recently a trend in the Remark/Rehype ecosystem to migrate to ES Modules, a new JavaScript module system, which Docusaurus doesn't support yet. Please make sure your installed plugin version is CommonJS-compatible before we officially support ESM. Alternatively, you can read about using dynamic `import()` as a workaround in the tutorial of installing [`rehype-katex`](./markdown-features-math-equations.mdx#upgrading-rehype-katex-beyond-recommended-version).
:::