feat: mathjax support (#2977)

docs/.vitepress/config.ts

@@ -12,6 +12,10 @@ export default defineConfig({
   lastUpdated: true,
   cleanUrls: true,
 
+  markdown: {
+    math: true
+  },
+
   sitemap: {
     hostname: 'https://vitepress.dev',
     transformItems(items) {

docs/guide/markdown.md

@@ -795,6 +795,51 @@ The format of the selected line range can be: `{3,}`, `{,10}`, `{1,10}`
 Note that this does not throw errors if your file is not present. Hence, when using this feature make sure that the contents are being rendered as expected.
 :::
 
+## Math Equations
+
+This is currently opt-in. To enable it, you need to install `markdown-it-mathjax3` and set `markdown.math` to `true` in your config file:
+
+```sh
+npm add -D markdown-it-mathjax3
+```
+
+```ts
+// .vitepress/config.ts
+export default {
+  markdown: {
+    math: true
+  }
+}
+```
+
+**Input**
+
+```md
+When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
+$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
+
+**Maxwell's equations:**
+
+| equation                                                                                                                                                                  | description                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| $\nabla \cdot \vec{\mathbf{B}}  = 0$                                                                                                                                      | divergence of $\vec{\mathbf{B}}$ is zero                                               |
+| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t}  = \vec{\mathbf{0}}$                                                          | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
+| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_                                                                                 |
+```
+
+**Output**
+
+When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
+$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
+
+**Maxwell's equations:**
+
+| equation                                                                                                                                                                  | description                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| $\nabla \cdot \vec{\mathbf{B}}  = 0$                                                                                                                                      | divergence of $\vec{\mathbf{B}}$ is zero                                               |
+| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t}  = \vec{\mathbf{0}}$                                                          | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
+| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_                                                                                 |
+
 ## Advanced Configuration
 
 VitePress uses [markdown-it](https://github.com/markdown-it/markdown-it) as the Markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the `markdown-it` instance using the `markdown` option in `.vitepress/config.js`:

docs/package.json

@@ -8,6 +8,7 @@
     "preview": "vitepress preview"
   },
   "devDependencies": {
+    "markdown-it-mathjax3": "^4.3.2",
     "vitepress": "workspace:*"
   }
 }

docs/reference/site-config.md

@@ -525,8 +525,24 @@ interface MarkdownOptions extends MarkdownIt.Options {
   // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
   toc?: TocPluginOptions
 
+  // @mdit-vue/plugin-component plugin options.
+  // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-component#options
+  component?: ComponentPluginOptions
+
   // Configure the Markdown-it instance.
   config?: (md: MarkdownIt) => void
+
+  // Same as `config` but will be applied before all other plugins.
+  preConfig?: (md: MarkdownIt) => void
+
+  // Disable cache (experimental)
+  cache?: boolean
+
+  // Math support (experimental)
+  // You need to install `markdown-it-mathjax3` and set `math` to `true` to enable it.
+  // You can also pass options to `markdown-it-mathjax3` here.
+  // See: https://github.com/tani/markdown-it-mathjax3#customization
+  math?: any
 }
 ```
 

package.json

@@ -102,6 +102,14 @@
     "vite": "^4.4.9",
     "vue": "^3.3.4"
   },
+  "peerDependencies": {
+    "markdown-it-mathjax3": "^4.3.2"
+  },
+  "peerDependenciesMeta": {
+    "markdown-it-mathjax3": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@clack/prompts": "^0.7.0",
     "@mdit-vue/plugin-component": "^0.12.1",
@@ -154,6 +162,7 @@
     "markdown-it-attrs": "^4.1.6",
     "markdown-it-container": "^3.0.0",
     "markdown-it-emoji": "^2.0.2",
+    "markdown-it-mathjax3": "^4.3.2",
     "micromatch": "^4.0.5",
     "minimist": "^1.2.8",
     "nanoid": "^4.0.2",