diff --git a/website/docs/guides/markdown-features/markdown-features-math-equations.mdx b/website/docs/guides/markdown-features/markdown-features-math-equations.mdx new file mode 100644 index 000000000000..15c1e670df3d --- /dev/null +++ b/website/docs/guides/markdown-features/markdown-features-math-equations.mdx @@ -0,0 +1,119 @@ +--- +id: math-equations +title: Math Equations +description: Writing LaTeX Math Equations +slug: /markdown-features/math-equations +--- + +Mathematical equations can be rendered using [KaTeX](https://katex.org). + +## Usage + +Please read [KaTeX](https://katex.org) documentation for more details. + +### Inline + +Write inline math equations by wrapping LaTeX equations between `$`: + +```mdx +Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[a,b]\to\R$ be $F(x)= +\int_{a}^{x}f(t)dt$. Then $$F$$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$. +``` + +Let $f:[a,b] \to \R$ be Riemann integrable. Let $F:[a,b]\to\R$ be $F(x)= +\int_{a}^{x}f(t)dt$. Then $F$ is continuous, and at all $x$ such that $f$ is continuous at $x$, $F$ is differentiable at $x$ with $F'(x)=f(x)$. + +### Blocks + +For equation block or display mode, use line breaks and `$$`: + +```mdx +$$ +I = \int_0^{2\pi} \sin(x) dx +$$ +``` + +$$ +I = \int_0^{2\pi} \sin(x) dx +$$ + +## Configuration + +To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins. + +```bash npm2yarn +npm install --save remark-math@3 rehype-katex@4 hast-util-is-element@1.1.0 +``` + +:::caution + +Use the exact same versions. The latest versions are incompatible with Docusaurus 2. + +::: + +Import the plugins in `docusaurus.config.js`: + +```js +const math = require('remark-math'); +const katex = require('rehype-katex'); +``` + +Add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options): + +```js +remarkPlugins: [math], +rehypePlugins: [katex], +``` + +Include the KaTeX CSS in your config under `stylesheets`: + +```js +stylesheets: [ + { + href: "https://cdn.jsdelivr.net/npm/katex@0.13.11/dist/katex.min.css", + type: "text/css", + integrity: "sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc", + crossorigin: "anonymous", + }, +], +``` + +Overall the changes look like: + +```diff title="docusaurus.config.js" +// highlight-start ++ const math = require('remark-math'); ++ const katex = require('rehype-katex'); +// highlight-end + + +module.exports = { + 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.13.11/dist/katex.min.css', ++ type: 'text/css', ++ integrity: ++ 'sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc', ++ crossorigin: 'anonymous', ++ }, ++ ], + // highlight-end +}; +``` diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 5d97fae6c78a..495849ba74b4 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -7,6 +7,8 @@ const path = require('path'); const versions = require('./versions.json'); +const math = require('remark-math'); +const katex = require('rehype-katex'); // This probably only makes sense for the beta phase, temporary function getNextBetaVersionName() { @@ -52,6 +54,15 @@ const isVersioningDisabled = !!process.env.DISABLE_VERSIONING || isI18nStaging; baseUrl, baseUrlIssueBanner: true, url: 'https://docusaurus.io', + stylesheets: [ + { + href: 'https://cdn.jsdelivr.net/npm/katex@0.13.11/dist/katex.min.css', + type: 'text/css', + integrity: + 'sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc', + crossorigin: 'anonymous', + }, + ], i18n: { defaultLocale: 'en', locales: isDeployPreview @@ -237,8 +248,10 @@ const isVersioningDisabled = !!process.env.DISABLE_VERSIONING || isI18nStaging; showLastUpdateAuthor: true, showLastUpdateTime: true, remarkPlugins: [ + math, [require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}], ], + rehypePlugins: [katex], disableVersioning: isVersioningDisabled, lastVersion: isDev ? 'current' : undefined, onlyIncludeVersions: diff --git a/website/package.json b/website/package.json index 3fb76140e8af..1e20edc7cc8c 100644 --- a/website/package.json +++ b/website/package.json @@ -44,6 +44,9 @@ "npm-to-yarn": "^1.0.0-2", "react": "^17.0.2", "react-dom": "^17.0.2", + "rehype-katex": "^4.0.0", + "remark-math": "^3.0.1", + "hast-util-is-element": "1.1.0", "workbox-routing": "^5.0.0", "workbox-strategies": "^5.0.0" }, diff --git a/website/sidebars.js b/website/sidebars.js index 50f341437073..3a6f8b18d8c1 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -43,6 +43,7 @@ module.exports = { 'guides/markdown-features/inline-toc', 'guides/markdown-features/assets', 'guides/markdown-features/plugins', + 'guides/markdown-features/math-equations', ], }, 'styling-layout', diff --git a/yarn.lock b/yarn.lock index 39a553635575..9afa4d0c95e1 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3516,6 +3516,11 @@ resolved "https://registry.yarnpkg.com/@types/json5/-/json5-0.0.29.tgz#ee28707ae94e11d2b827bcbe5270bcea7f3e71ee" integrity sha1-7ihweulOEdK4J7y+UnC86n8+ce4= +"@types/katex@^0.11.0": + version "0.11.0" + resolved "https://registry.yarnpkg.com/@types/katex/-/katex-0.11.0.tgz#b16c54ee670925ffef0616beae9e90c557e17334" + integrity sha512-27BfE8zASRLYfSBNMk5/+KIjr2CBBrH0i5lhsO04fca4TGirIIMay73v3zNkzqmsaeIa/Mi5kejWDcxPLAmkvA== + "@types/loader-utils@^2.0.2": version "2.0.2" resolved "https://registry.yarnpkg.com/@types/loader-utils/-/loader-utils-2.0.2.tgz#2999dc2a3330b3ac0b2eaa9e01328b3484ef1112" @@ -10098,10 +10103,10 @@ hast-util-from-parse5@^6.0.0: vfile "^4.0.0" web-namespaces "^1.0.0" -hast-util-is-element@^1.0.0: - version "1.0.4" - resolved "https://registry.yarnpkg.com/hast-util-is-element/-/hast-util-is-element-1.0.4.tgz#059090a05cc02e275df1ad02caf8cb422fcd2e02" - integrity sha512-NFR6ljJRvDcyPP5SbV7MyPBgF47X3BsskLnmw1U34yL+X6YC0MoBx9EyMg8Jtx4FzGH95jw8+c1VPLHaRA0wDQ== +hast-util-is-element@1.1.0, hast-util-is-element@^1.0.0: + version "1.1.0" + resolved "https://registry.yarnpkg.com/hast-util-is-element/-/hast-util-is-element-1.1.0.tgz#3b3ed5159a2707c6137b48637fbfe068e175a425" + integrity sha512-oUmNua0bFbdrD/ELDSSEadRVtWZOf3iF6Lbv81naqsIV99RnSCieTbWuWCY8BAeEfKJTKl0gRdokv+dELutHGQ== hast-util-parse-selector@^2.0.0: version "2.2.3" @@ -10140,7 +10145,7 @@ hast-util-to-string@^1.0.4: resolved "https://registry.yarnpkg.com/hast-util-to-string/-/hast-util-to-string-1.0.4.tgz#9b24c114866bdb9478927d7e9c36a485ac728378" integrity sha512-eK0MxRX47AV2eZ+Lyr18DCpQgodvaS3fAQO2+b9Two9F5HEoRPhiUMNzoXArMJfZi2yieFzUBMRl3HNJ3Jus3w== -hast-util-to-text@^2.0.1: +hast-util-to-text@^2.0.0, hast-util-to-text@^2.0.1: version "2.0.1" resolved "https://registry.yarnpkg.com/hast-util-to-text/-/hast-util-to-text-2.0.1.tgz#04f2e065642a0edb08341976084aa217624a0f8b" integrity sha512-8nsgCARfs6VkwH2jJU9b8LNTuR4700na+0h3PqCaEk4MAnMDeu5P0tP8mjk9LLNGxIeQRLbiDbZVw6rku+pYsQ== @@ -12061,6 +12066,13 @@ jwt-decode@^2.2.0: resolved "https://registry.yarnpkg.com/jwt-decode/-/jwt-decode-2.2.0.tgz#7d86bd56679f58ce6a84704a657dd392bba81a79" integrity sha1-fYa9VmefWM5qhHBKZX3TkruoGnk= +katex@^0.12.0: + version "0.12.0" + resolved "https://registry.yarnpkg.com/katex/-/katex-0.12.0.tgz#2fb1c665dbd2b043edcf8a1f5c555f46beaa0cb9" + integrity sha512-y+8btoc/CK70XqcHqjxiGWBOeIL8upbS0peTPXTvgrh21n1RiWWcIpSWM+4uXq+IAgNh9YYQWdc7LVDPDAEEAg== + dependencies: + commander "^2.19.0" + kebab-case@^1.0.0: version "1.0.0" resolved "https://registry.yarnpkg.com/kebab-case/-/kebab-case-1.0.0.tgz#3f9e4990adcad0c686c0e701f7645868f75f91eb" @@ -16786,6 +16798,18 @@ regjsparser@^0.6.4: dependencies: jsesc "~0.5.0" +rehype-katex@^4.0.0: + version "4.0.0" + resolved "https://registry.yarnpkg.com/rehype-katex/-/rehype-katex-4.0.0.tgz#ce11a5db0bff014350e7a9cfd30147d314b14330" + integrity sha512-0mgBqYugQyIW0eUl6RDOZ28Cat2YzrnWGaYgKCMQnJw6ClmKgLqXBnkDAPGh2mwxvkkKwQOUMUpSLpA5rt7rzA== + dependencies: + "@types/katex" "^0.11.0" + hast-util-to-text "^2.0.0" + katex "^0.12.0" + rehype-parse "^7.0.0" + unified "^9.0.0" + unist-util-visit "^2.0.0" + rehype-parse@^6.0.2: version "6.0.2" resolved "https://registry.yarnpkg.com/rehype-parse/-/rehype-parse-6.0.2.tgz#aeb3fdd68085f9f796f1d3137ae2b85a98406964" @@ -16795,7 +16819,7 @@ rehype-parse@^6.0.2: parse5 "^5.0.0" xtend "^4.0.0" -rehype-parse@^7.0.1: +rehype-parse@^7.0.0, rehype-parse@^7.0.1: version "7.0.1" resolved "https://registry.yarnpkg.com/rehype-parse/-/rehype-parse-7.0.1.tgz#58900f6702b56767814afc2a9efa2d42b1c90c57" integrity sha512-fOiR9a9xH+Le19i4fGzIEowAbwG7idy2Jzs4mOrFWBSJ0sNUgy0ev871dwWnbOo371SjgjG4pwzrbgSVrKxecw== @@ -16831,6 +16855,11 @@ remark-footnotes@2.0.0: resolved "https://registry.yarnpkg.com/remark-footnotes/-/remark-footnotes-2.0.0.tgz#9001c4c2ffebba55695d2dd80ffb8b82f7e6303f" integrity sha512-3Clt8ZMH75Ayjp9q4CorNeyjwIxHFcTkaektplKGl2A1jNGEUey8cKL0ZC5vJwfcD5GFGsNLImLG/NGzWIzoMQ== +remark-math@^3.0.1: + version "3.0.1" + resolved "https://registry.yarnpkg.com/remark-math/-/remark-math-3.0.1.tgz#85a02a15b15cad34b89a27244d4887b3a95185bb" + integrity sha512-epT77R/HK0x7NqrWHdSV75uNLwn8g9qTyMqCRCDujL0vj/6T6+yhdrR7mjELWtkse+Fw02kijAaBuVcHBor1+Q== + remark-mdx@1.6.22, remark-mdx@^1.6.21: version "1.6.22" resolved "https://registry.yarnpkg.com/remark-mdx/-/remark-mdx-1.6.22.tgz#06a8dab07dcfdd57f3373af7f86bd0e992108bbd"