docs: Document configuration of the remark-math plugin

[waldyrious]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

Using the remark-math plugin with its default configuration (where single dollar signs, i.e. $...$, are interpreted as delimiting inline math) can result in unintended rendering changes in pages that happen to contain lines with two or more dollar signs, e.g. to indicate prices of items or other monetary amounts.

This issue has been identified by others in the plugin's issue tracker, and the proposed solution is to set the configuration option singleDollarTextMath to false. However, the exact syntax to set that option in the context of a docusaurus.config.js file is not immediately clear.

This PR explicitly documents that configuration option, explains when one might want to use it, and provides an usage example.

Test Plan

Test links

Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/

[Josh-Cena]

Hi there, thanks for the PR! This doc documents an external plugin. We are not interested in documenting any of its behaviors, only how to use it with Docusaurus. Anything documentation that can exist outside of the context of Docusaurus should be found in its own documentation.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	Report
/	🟠 62	🟢 98	🟢 96	🟢 100	Report
/docs/installation	🔴 49	🟢 97	🟢 100	🟢 100	Report
/docs/category/getting-started	🟠 72	🟢 100	🟢 100	🟠 86	Report
/blog	🟠 61	🟢 96	🟢 100	🟠 86	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 62	🟢 92	🟢 100	🟢 100	Report
/blog/tags/release	🟠 62	🟢 96	🟢 100	🟠 86	Report
/blog/tags	🟠 73	🟢 100	🟢 100	🟠 86	Report

[waldyrious]

We are not interested in documenting any of its behaviors, only how to use it with Docusaurus

That's precisely what I intended with this PR — to document how to set it up in Docusaurus, especially the singleDollarTextMath is the only configuration option for this plugin, and addresses a very common issue. I added a bit more context in the spirit of making the documentation maximally useful, but the core of this contribution is the configuration option, so I wouldn't object to removing that usage example.

Would it be acceptable if instead of adding a new section to this page, we simply modify the existing configuration snippet to include the (only) configuration option?

-remarkPlugins: [remarkMath],
+remarkPlugins: [[remarkMath, {singleDollarTextMath: true|false}]],

[Josh-Cena]

Documentation for how to add configuration is already in https://docusaurus.io/docs/markdown-features/plugins#configuring-plugins. I don't think we want to mention anything specific about how this plugin works.

[slorber]

The options are documented here

• https://github.com/remarkjs/remark-math/tree/main/packages/remark-math#options
• https://github.com/remarkjs/remark-math/tree/main/packages/rehype-katex#options

At best, I'd prefer to link to these pages in a generic way, and not listing any option attribute in our docs

-remarkPlugins: [remarkMath],

+// For available options, see: https://github.com/remarkjs/remark-math/tree/main/packages/remark-math#options
+remarkPlugins: [[remarkMath, remarkMathOptions]],

If we document remark-math options, then we'd probably want to do the same for rehype-katex too for consistency. After all, if a plugin has a single option, it doesn't mean we should document it while we keep all other plugins undocumented. And we clearly don't want to document all the possible options available (see https://katex.org/docs/options.html)