Add LaTeX support (#1143)

.changeset/angry-years-drum.md

@@ -0,0 +1,5 @@
+---
+"nextra": patch
+---
+
+Add LaTeX support

examples/docs/next.config.js

@@ -2,6 +2,7 @@ const withNextra = require('nextra')({
   theme: 'nextra-theme-docs',
   themeConfig: './src/theme.config.js',
   staticImage: true,
+  latex: true,
   flexsearch: {
     codeblock: false
   }

examples/docs/src/pages/features/_meta.json

@@ -3,5 +3,6 @@
   "ssg": "Next.js SSG",
   "i18n": "Next.js i18n",
   "image": "Next.js Image",
-  "themes": "Themes"
+  "themes": "Themes",
+  "latex": "LaTeX"
 }

examples/docs/src/pages/features/latex.mdx

@@ -0,0 +1,18 @@
+# LaTeX
+
+Nextra uses [KaTeX](https://katex.org/) to render LaTeX expressions directly in MDX.
+To enable LaTeX support, you must add the following to your `next.config.js`:
+
+```js filename="next.config.js"
+module.exports = require('nextra')({
+  latex: true,
+})
+```
+
+Using LaTeX within MDX is as simple as wrapping your expression in `$$` or `$`. For example, the following code
+```latex
+$\sqrt{a^2 + b^2}$
+```
+will be rendered as: $\sqrt{a^2 + b^2}$
+
+To learn more about KaTeX and its supported functions, visit their [documentation](https://katex.org/docs/supported.html).

packages/nextra/package.json

@@ -81,10 +81,13 @@
     "github-slugger": "^2.0.0",
     "graceful-fs": "^4.2.10",
     "gray-matter": "^4.0.3",
+    "katex": "^0.16.4",
     "p-limit": "^3.1.0",
+    "rehype-katex": "^6.0.2",
     "rehype-mdx-title": "^2.0.0",
     "rehype-pretty-code": "0.6.0",
     "remark-gfm": "^3.0.1",
+    "remark-math": "^5.1.1",
     "remark-reading-time": "^2.0.1",
     "shiki": "0.12.1",
     "slash": "^3.0.0",

packages/nextra/src/compile.ts

@@ -14,6 +14,8 @@ import {
 import { LoaderOptions, PageOpts, ReadingTime } from './types'
 import theme from './theme.json'
 import { truthy } from './utils'
+import remarkMath from 'remark-math'
+import rehypeKatex from 'rehype-katex'
 
 const createCompiler = (mdxOptions: ProcessorOptions): Processor => {
   const compiler = createProcessor(mdxOptions)
@@ -44,7 +46,11 @@ export async function compileMdx(
   source: string,
   loaderOptions: Pick<
     LoaderOptions,
-    'staticImage' | 'flexsearch' | 'defaultShowCopyCode' | 'readingTime'
+    | 'staticImage'
+    | 'flexsearch'
+    | 'defaultShowCopyCode'
+    | 'readingTime'
+    | 'latex'
   > & {
     mdxOptions?: LoaderOptions['mdxOptions'] &
       Pick<ProcessorOptions, 'jsx' | 'outputFormat'>
@@ -66,7 +72,8 @@ export async function compileMdx(
       loaderOptions.staticImage && ([remarkStaticImage, { filePath }] as any),
       loaderOptions.flexsearch &&
         structurize(structurizedData, loaderOptions.flexsearch),
-      loaderOptions.readingTime && readingTime
+      loaderOptions.readingTime && readingTime,
+      loaderOptions.latex && remarkMath
     ].filter(truthy),
     rehypePlugins: [
       ...(mdxOptions.rehypePlugins || []),
@@ -76,7 +83,8 @@ export async function compileMdx(
         { ...rehypePrettyCodeOptions, ...mdxOptions.rehypePrettyCodeOptions }
       ],
       [rehypeMdxTitle, { name: '__nextra_title__' }],
-      [attachMeta, { defaultShowCopyCode: loaderOptions.defaultShowCopyCode }]
+      [attachMeta, { defaultShowCopyCode: loaderOptions.defaultShowCopyCode }],
+      ...(loaderOptions.latex ? [rehypeKatex] : [])
     ]
   })
   try {

packages/nextra/src/loader.ts

@@ -67,6 +67,7 @@ async function loader(
     defaultLocale,
     defaultShowCopyCode,
     flexsearch,
+    latex,
     staticImage,
     readingTime: _readingTime,
     mdxOptions,
@@ -127,14 +128,18 @@ async function loader(
         readingTime: _readingTime,
         defaultShowCopyCode,
         staticImage,
-        flexsearch
+        flexsearch,
+        latex
       },
       mdxPath
     )
-  // @ts-expect-error
-  const cssImport = OFFICIAL_THEMES.includes(theme)
-    ? `import '${theme}/style.css'`
-    : ''
+
+  const katexCss = latex ? "import 'katex/dist/katex.min.css'\n" : ''
+
+  const cssImport =
+    katexCss +
+    // @ts-expect-error
+    (OFFICIAL_THEMES.includes(theme) ? `import '${theme}/style.css'` : '')
 
   // Imported as a normal component, no need to add the layout.
   if (!pageImport) {

packages/nextra/src/types.ts

@@ -94,6 +94,7 @@ export type NextraConfig = {
   flexsearch?: Flexsearch
   staticImage?: boolean
   readingTime?: boolean
+  latex?: boolean
   mdxOptions?: Pick<ProcessorOptions, 'rehypePlugins' | 'remarkPlugins'> & {
     rehypePrettyCodeOptions?: Partial<RehypePrettyCodeOptions>
   }