docs(v2): New doc page for math equations

[pranabdas]

Motivation

Rendering LaTeX math equations is an important feature for many documentation sites. Although, it is possible to write math equations using Docusaurus, it is not documented in the Docs.

Have you read the Contributing Guidelines on pull requests?

Yes.

Test Plan

I have created a new file website/docs/guides/markdown-features/markdown-features-math-equations.mdx, and made changes to the sidebar configuration (website/sidebars.js) to include it in the sidebar. I have tested the doc website locally, and it works properly.

Related PRs

• LaTex integration  #4017

[netlify]

✔️ [V2]

🔨 Explore the source changes: 543d3fa

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/60b772e3e9d6470008a9861a

😎 Browse the preview: https://deploy-preview-4821--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	51
🟢 Accessibility	97
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-4821--docusaurus-2.netlify.app/

[slorber]

Hey, thanks for this doc

I've updated it a bit and enabled Katex on Docusaurus site for dogfooding and ensure this remains usable.

Helped me figure out some potential problems in versions (hast-util-is-element absolutely need to be 1.1.0 or it won't work)

[netlify]

✔️ [V1]

🔨 Explore the source changes: 543d3fa

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-1/deploys/60b772e390075e0008b49473

😎 Browse the preview: https://deploy-preview-4821--docusaurus-1.netlify.app

[pranabdas]

Thank you for catching the dependencies. I did not test on Docusaurus website (was not sure if it would be good idea to change package.json). For me it worked fine on a cleanly built site:

npm i @docusaurus/core@latest @docusaurus/preset-classic@latest
npm i remark-math@3 rehype-katex

[slorber]

rehype-katex has published v5 recently, I'm not sure it's compatible anymore. In any case I think it's preferable to lock to specific major versions as our doc may start failing other time when new incompatible majors are released

[pranabdas]

I updated some of my Doc sites to rehype-katex v5 along with docusaurus v2-beta0 couple of weeks ago. Have not noticed any glitch yet (an example page with lots of math equations). But it make sense to lock major versions, and upgrade manually.

[slorber]

hey @pranabdas , was wondering how did you decide to use an external cdn URL for this asset.

As I'm having network issues, this resource is blocking and preventing me to work locally easily

So I'll move the docusaurus site to self-hosted CSS to unblock me, but we should probably recommend users to do the same 🤷‍♂️

[pranabdas]

Hello @slorber, I did not think about its pros and cons much. Probably there is not much of cons hosting katex.min.css locally, as it is only 23 KB and relatively low chance that it would be cached by the browser (because the user downloaded the same resource used in another website).

[pranabdas]

@slorber I also realise that we need to host required katex fonts alongside katex stylesheet. Total asset size is ~1.2MB. Is that much build size increase acceptable? If you like, I can create a PR with proposed changes. Thank you.