💰 Dollarmath settings for markdown parsing (#2542)

See #2477

Author: rowanc1

.changeset/twenty-impalas-tap.md

@@ -0,0 +1,6 @@
+---
+'myst-frontmatter': patch
+'myst-cli': patch
+---
+
+Add dollarmath parser settings to project

docs/settings.md

@@ -60,6 +60,31 @@ output_matplotlib_strings
     - `"remove-warn"` (default) or `"remove-error"`: remove all matplotlib strings in outputs, and log a warning or error
     - `"warn"` or "error": log a warning or error if matplotlib strings in outputs
 
+## Markdown Parsing Settings
+
+Adding an object of `parser` to the settings will allow you to control various parser behaviors.
+
+```{code-block} yaml
+:filename: myst.yml
+project:
+  settings:
+    parser:
+      dollarmath: false
+```
+
+:::{warning}
+Markdown parsing settings currently only work on the `myst.yml` project settings, not the page frontmatter.
+:::
+
+(setting:parser:dollarmath)=
+dollarmath
+: Enable or disable inline dollar math parsing (e.g., `$x^2$` syntax).
+
+    - `true` (default): Enable inline dollar math parsing
+    - `false`: Disable inline dollar math parsing
+
+    When disabled, dollar signs (`$`) will be treated as regular text characters and not parsed as math delimiters. This can be useful if you have frequent uses of dollar signs, such as currency, in your content that are not meant to be math.
+
 ## LaTeX Rendering Settings
 
 Adding an object of `myst_to_tex` to the settings will allow you to control various default parts of how the LaTeX renderer behaves.

packages/myst-cli/src/process/myst.ts

@@ -9,6 +9,7 @@ import { VFile } from 'vfile';
 import type { ISession } from '../session/types.js';
 import { logMessagesFromVFile } from '../utils/logging.js';
 import type { GenericParent } from 'myst-common';
+import { selectCurrentProjectConfig } from '../store/selectors.js';
 
 /**
  * Boiled-down options for parseMyst
@@ -21,6 +22,16 @@ type Options = {
 };
 
 export function getMystParserOptions(session: ISession, opts?: Options): Partial<AllOptions> {
+  // Get parser settings from project config
+  // Right now this is only project level, but in the future we will allow page level settings.
+  const parserOptions = selectCurrentProjectConfig(session.store.getState())?.settings?.parser;
+  // Configure math extensions based on parser settings
+  let mathExtension: boolean | { dollarmath?: boolean; amsmath?: boolean } = true;
+  if (parserOptions?.dollarmath === false) {
+    // If dollarmath is explicitly disabled, configure math to only enable amsmath
+    mathExtension = { dollarmath: false, amsmath: true };
+  }
+
   return {
     markdownit: { linkify: true },
     directives: [
@@ -33,6 +44,7 @@ export function getMystParserOptions(session: ISession, opts?: Options): Partial
     ],
     extensions: {
       frontmatter: !opts?.ignoreFrontmatter,
+      math: mathExtension,
     },
     roles: [buttonRole, ...(session.plugins?.roles ?? [])],
   };

packages/myst-cli/src/process/notebook.ts

@@ -7,7 +7,6 @@ import type {
   ICell,
   IMimeBundle,
   INotebookContent,
-  INotebookMetadata,
   IOutput,
   MultilineString,
 } from '@jupyterlab/nbformat';

packages/myst-frontmatter/src/settings/index.ts

@@ -1,3 +1,4 @@
 export * from './types.js';
 export * from './validators.js';
 export * from './validatorsMystToTex.js';
+export * from './validatorsParser.js';

packages/myst-frontmatter/src/settings/parser.yml

@@ -0,0 +1,47 @@
+title: parser
+frontmatter: project
+cases:
+  - title: unknown option
+    raw:
+      settings:
+        parser:
+          unknown: unknown
+    warnings: 1
+    normalized: {}
+  - title: dollarmath true
+    raw:
+      settings:
+        parser:
+          dollarmath: true
+    errors: 0
+    normalized:
+      settings:
+        parser:
+          dollarmath: true
+  - title: dollarmath false
+    raw:
+      settings:
+        parser:
+          dollarmath: false
+    errors: 0
+    normalized:
+      settings:
+        parser:
+          dollarmath: false
+  - title: dollarmath with alias
+    raw:
+      settings:
+        parser:
+          dollar_math: false
+    errors: 0
+    normalized:
+      settings:
+        parser:
+          dollarmath: false
+  - title: dollarmath invalid boolean
+    raw:
+      settings:
+        parser:
+          dollarmath: invalid
+    errors: 1
+    normalized: {}

packages/myst-frontmatter/src/settings/types.ts

@@ -5,9 +5,14 @@ export type MystToTexSettings = {
   beamer?: boolean;
 };
 
+export type ParserSettings = {
+  dollarmath?: boolean;
+};
+
 export type ProjectSettings = {
   output_stderr?: OutputRemovalOptions;
   output_stdout?: OutputRemovalOptions;
   output_matplotlib_strings?: OutputRemovalOptions;
   myst_to_tex?: MystToTexSettings;
+  parser?: ParserSettings;
 };

packages/myst-frontmatter/src/settings/validators.ts

@@ -2,6 +2,7 @@ import type { ValidationOptions } from 'simple-validators';
 import { defined, incrementOptions, validateChoice, validateObjectKeys } from 'simple-validators';
 import type { ProjectSettings } from './types.js';
 import { validateMystToTexSettings } from './validatorsMystToTex.js';
+import { validateParserSettings } from './validatorsParser.js';
 
 const OUTPUT_REMOVAL_OPTIONS: Required<ProjectSettings>['output_stderr'][] = [
   'show',
@@ -16,6 +17,7 @@ export const PROJECT_SETTINGS = [
   'output_stdout',
   'output_matplotlib_strings',
   'myst_to_tex',
+  'parser',
 ];
 export const PROJECT_SETTINGS_ALIAS = {
   stderr_output: 'output_stderr',
@@ -63,6 +65,10 @@ export function validateProjectAndPageSettings(
     );
     if (myst_to_tex) output.myst_to_tex = myst_to_tex;
   }
+  if (defined(settings.parser)) {
+    const parser = validateParserSettings(settings.parser, incrementOptions('parser', opts));
+    if (parser) output.parser = parser;
+  }
   if (Object.keys(output).length === 0) return undefined;
   return output;
 }

packages/myst-frontmatter/src/settings/validatorsParser.ts

@@ -0,0 +1,27 @@
+import type { ValidationOptions } from 'simple-validators';
+import { defined, incrementOptions, validateBoolean, validateObjectKeys } from 'simple-validators';
+import type { ParserSettings } from './types.js';
+
+export const PARSER_SETTINGS = ['dollarmath'];
+export const PARSER_SETTINGS_ALIAS = {
+  dollar_math: 'dollarmath',
+};
+
+export function validateParserSettings(
+  value: Record<string, any>,
+  opts: ValidationOptions,
+): ParserSettings | undefined {
+  const output: ParserSettings = {};
+  const settings = validateObjectKeys(
+    value,
+    { optional: PARSER_SETTINGS, alias: PARSER_SETTINGS_ALIAS },
+    opts,
+  );
+  if (!settings) return undefined;
+  if (defined(settings.dollarmath)) {
+    const dollarmath = validateBoolean(settings.dollarmath, incrementOptions('dollarmath', opts));
+    if (dollarmath != null) output.dollarmath = dollarmath;
+  }
+  if (Object.keys(output).length === 0) return undefined;
+  return output;
+}