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

docs(math): use list of steps for clearer guidance (#9659)

Browse source 
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
This commit is contained in:
Arthur 2023-12-22 13:15:25 +01:00 • committed by GitHub
parent a180a3012f
commit d9d700c54f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 86 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -49,30 +49,32 @@ $$
</BrowserWindow> </BrowserWindow>
## Configuration {#configuration} ## Enabling math equations {#configuration}
To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins. Enable KaTeX:
```bash npm2yarn 1. Install the `remark-math` and `rehype-katex` plugins:
npm install --save remark-math@6 rehype-katex@7
```
:::warning ```bash npm2yarn
npm install --save remark-math@6 rehype-katex@7
```
Make sure to use `remark-math 6` and `rehype-katex 7` for Docusaurus v3 (using MDX v3). We can't guarantee other versions will work. :::warning
::: Make sure to use `remark-math 6` and `rehype-katex 7` for Docusaurus v3 (using MDX v3). We can't guarantee other versions will work.
Those 2 plugins are now [**only available as ES Modules**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). To simplify usage, it is recommended to use an [**ES Modules**](https://flaviocopes.com/es-modules/) config file: :::
```js title="ES module docusaurus.config.js" 2. These 2 plugins are [**only available as ES Modules**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). We recommended to use an [**ES Modules**](https://flaviocopes.com/es-modules/) config file:
// highlight-start
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
// highlight-end
// highlight-start ```js title="ES module docusaurus.config.js"
export default { // highlight-start
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
// highlight-end
// highlight-start
export default {
presets: [ presets: [
[ [
'@docusaurus/preset-classic', '@docusaurus/preset-classic',
@ -87,17 +89,22 @@ export default {
}, },
], ],
], ],
}; };
``` ```
<details> <details>
<summary>Using a [**CommonJS**](https://nodejs.org/api/modules.html#modules-commonjs-modules) config file?</summary>
<summary>
Using a
[**CommonJS**](https://nodejs.org/api/modules.html#modules-commonjs-modules)
config file?
</summary>
If you decide to use a CommonJS config file, it is possible to load those ES module plugins thanks to dynamic imports and an async config creator function: If you decide to use a CommonJS config file, it is possible to load those ES module plugins thanks to dynamic imports and an async config creator function:
```js title="CommonJS module docusaurus.config.js" ```js title="CommonJS module docusaurus.config.js"
// highlight-start // highlight-start
module.exports = async function createConfigAsync() { module.exports = async function createConfigAsync() {
// highlight-end // highlight-end
return { return {
presets: [ presets: [
@ -115,15 +122,17 @@ module.exports = async function createConfigAsync() {
], ],
], ],
}; };
}; };
``` ```
</details> </details>
Include the KaTeX CSS in your config under `stylesheets`: 3. Include the KaTeX CSS in your config under `stylesheets`:
```js ```js
stylesheets: [ export default {
//...
stylesheets: [
{ {
href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css', href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
type: 'text/css', type: 'text/css',
@ -131,10 +140,12 @@ stylesheets: [
'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM', 'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
crossorigin: 'anonymous', crossorigin: 'anonymous',
}, },
], ],
``` };
```
Overall the changes look like: <details>
<summary>See a config file example</summary>
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
// highlight-start // highlight-start
@ -173,6 +184,8 @@ export default {
}; };
``` ```
</details>
## Self-hosting KaTeX assets {#self-hosting-katex-assets} ## Self-hosting KaTeX assets {#self-hosting-katex-assets}
Loading stylesheets, fonts, and JavaScript libraries from CDN sources is a good practice for popular libraries and assets, since it reduces the amount of assets you have to host. In case you prefer to self-host the `katex.min.css` (along with required KaTeX fonts), you can download the latest version from [KaTeX GitHub releases](https://github.com/KaTeX/KaTeX/releases), extract and copy `katex.min.css` and `fonts` directory (only `.woff2` font types should be enough) to your site's `static` directory, and in `docusaurus.config.js`, replace the stylesheet's `href` from the CDN URL to your local path (say, `/katex/katex.min.css`). Loading stylesheets, fonts, and JavaScript libraries from CDN sources is a good practice for popular libraries and assets, since it reduces the amount of assets you have to host. In case you prefer to self-host the `katex.min.css` (along with required KaTeX fonts), you can download the latest version from [KaTeX GitHub releases](https://github.com/KaTeX/KaTeX/releases), extract and copy `katex.min.css` and `fonts` directory (only `.woff2` font types should be enough) to your site's `static` directory, and in `docusaurus.config.js`, replace the stylesheet's `href` from the CDN URL to your local path (say, `/katex/katex.min.css`).