improve math equations doc

facebook · Jun 2, 2021 · 543d3fa · 543d3fa
1 parent 7a231c2
commit 543d3fa
Show file tree

Hide file tree

Showing 4 changed files with 112 additions and 53 deletions.
diff --git a/website/docs/guides/markdown-features/markdown-features-math-equations.mdx b/website/docs/guides/markdown-features/markdown-features-math-equations.mdx
@@ -5,34 +5,67 @@ description: Writing LaTeX Math Equations
 slug: /markdown-features/math-equations
 ---
 
-Mathematical equations can be rendered using [KaTeX](https://katex.org). To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins.
+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
-npm install --save rehype-katex
+npm install --save remark-math@3 rehype-katex@4 [email protected]
 ```
 
 :::caution
 
-Note that the latest versin of `remark-math 4` is not compatible with current version of `docusaurus 2` yet. Therefore, `remark-math@3` is used.
+Use the exact same versions. The latest versions are incompatible with Docusaurus 2.
 
 :::
 
-You need to include following configuration changes in `docusaurus.config.js`. First, import the plugins at the top of `docusaurus.config.js`:
+Import the plugins in `docusaurus.config.js`:
 
 ```js
 const math = require('remark-math');
 const katex = require('rehype-katex');
 ```
 
-Add them to `@docusaurus/preset-classic` in options in `docusaurus.config.js`:
+Add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options):
 
 ```js
 remarkPlugins: [math],
 rehypePlugins: [katex],
 ```
 
-And finally, add include custom `stylesheets` under `module.exports` for KaTeX:
+Include the KaTeX CSS in your config under `stylesheets`:
 
 ```js
 stylesheets: [
@@ -45,61 +78,42 @@ stylesheets: [
 ],
 ```
 
-Overall the changes will look like:
+Overall the changes look like:
 
-```js title="docusaurus.config.js"
+```diff title="docusaurus.config.js"
 // highlight-start
-const math = require("remark-math");
-const katex = require("rehype-katex");
++ const math = require('remark-math');
++ const katex = require('rehype-katex');
 // highlight-end
-(module.exports = {
+
+
+module.exports = {
   title: 'Docusaurus',
   tagline: 'Build optimized websites quickly, focus on your content',
-  organizationName: 'facebook',
-  projectName: 'docusaurus',
-  ...
   presets: [
     [
-      isBootstrapPreset
-        ? '@docusaurus/preset-bootstrap'
-        : '@docusaurus/preset-classic',
+      '@docusaurus/preset-classic',
       {
-        debug: true, // force debug plugin usage
         docs: {
-          // routeBasePath: '/',
           path: 'docs',
-          sidebarPath: require.resolve('./sidebars.js'),
           // highlight-start
-          remarkPlugins: [math],
-          rehypePlugins: [katex],
++         remarkPlugins: [math],
++         rehypePlugins: [katex],
           // highlight-end
-          ...
         },
-      }
-      ...
+      },
     ],
   ],
   // highlight-start
-  stylesheets: [
-  {
-      href: "https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css",
-      type: "text/css",
-      integrity: "sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc",
-      crossorigin: "anonymous",
-  },
-  ],
++ stylesheets: [
++   {
++     href: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css',
++     type: 'text/css',
++     integrity:
++       'sha384-Um5gpz1odJg5Z4HAmzPtgZKdTBHZdw8S29IecapCSB31ligYPhHQZMIlWLYQGVoc',
++     crossorigin: 'anonymous',
++   },
++ ],
   // highlight-end
-});
-```
-
-Now you can write inline math equations in your markdown pages by wrapping LaTeX equations between `$$` e.g., `$$\pi$$`. For equation block or display mode, use line breaks for wrapping `$$`:
-
-```mdx
-Text with inline math $$\psi(x)$$.
-
-$$
-I = \int_0^{2\pi} \sin(x) dx
-$$
-
-More text follows.
+};
 ```
diff --git 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/[email protected]/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
@@ -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/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 @@ [email protected]:
   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==
+
 [email protected], remark-mdx@^1.6.21:
   version "1.6.22"
   resolved "https://registry.yarnpkg.com/remark-mdx/-/remark-mdx-1.6.22.tgz#06a8dab07dcfdd57f3373af7f86bd0e992108bbd"