mathpix-markdown-it 2.0.35 → 2.0.37

package/README.md

@@ -691,6 +691,127 @@ import {
 <img width="370" alt="Screen Shot 2022-05-03 at 17 21 50" src="https://user-images.githubusercontent.com/32493105/166471623-fd3f6a5b-84e4-4d43-afcd-0384e83eb2df.png">
 
 
+## Output Format
+
+The `output_format` option in `TOutputMath` controls which math format is placed in the HTML output. This is useful for optimizing file size or delegating rendering to the client.
+
+| Value | Description |
+|-------|-------------|
+| `'svg'` (default) | Pre-rendered SVG with hidden format elements. Works offline, no client-side rendering needed. |
+| `'mathml'` | Native `<math>` elements only. Smaller file size, requires client-side rendering via `auto-render.js`. |
+| `'latex'` | Raw LaTeX with original delimiters. Smaller file size, requires client-side rendering via `auto-render.js`. |
+
+### Example usage
+
+```js
+const options = {
+  outMath: {
+    output_format: 'mathml', // or 'latex'
+    include_mathml: true,
+    include_latex: true,
+  }
+};
+const html = MathpixMarkdownModel.markdownToHTML('$x^2$', options);
+```
+
+When using `'mathml'` or `'latex'`, the server outputs minimal HTML containing only the raw format. Use the browser rendering script (`auto-render.js`) to transform this into the full structure with SVG and hidden formats.
+
+
+## Browser Rendering Script (auto-render.js)
+
+For `output_format: 'mathml'` or `output_format: 'latex'`, use the browser bundle to render math on the client side.
+
+### Loading the script
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/mathpix-markdown-it@latest/es5/browser/auto-render.js"></script>
+```
+
+### Usage
+
+```js
+// Render all math elements in a container
+window.MathpixRender.renderMathInElement(document.getElementById('content'), {
+  outMath: {
+    output_format: 'svg',
+    include_svg: true,
+    include_mathml: true,
+    include_latex: true,
+    include_asciimath: true,
+  },
+  accessibility: {
+    assistive_mml: true,
+    include_speech: true,
+  }
+});
+```
+
+### Configuration options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `outMath` | `TOutputMath` | `{ output_format: 'svg', include_svg: true }` | Controls which hidden formats to generate. Set `include_mathml`, `include_latex`, `include_asciimath`, etc. to `true` to generate hidden format elements for context menu compatibility. |
+| `accessibility.assistive_mml` | `boolean` | `true` | Add `<mjx-assistive-mml>` element for screen readers |
+| `accessibility.include_speech` | `boolean` | `false` | Add `aria-label` with speech text (requires `assistive_mml: true`) |
+
+### Accessibility behavior
+
+The browser bundle uses a simplified accessibility configuration (different from the server-side [TAccessibility](#taccessibility) interface):
+
+| Configuration | Result |
+|---------------|--------|
+| `{ assistive_mml: true, include_speech: true }` | `aria-label` attribute with speech text + `<mjx-assistive-mml>` element |
+| `{ assistive_mml: true }` | `aria-labelledby` pointing to `<mjx-assistive-mml>` ID |
+| No accessibility config | No accessibility attributes added |
+
+The script automatically skips elements that have already been rendered.
+
+**Note:** For server-side rendering accessibility, use the [TAccessibility](#taccessibility) interface with `assistiveMml` and `sre` options instead.
+
+
+## Browser Speech Script (add-speech.js)
+
+Use this script to add speech accessibility to math that was already rendered server-side as SVG with `assistiveMml: true` but without SRE speech. It loads SRE dynamically and adds `aria-label` attributes to existing `mjx-container` elements.
+
+This is useful when you want fast server-side rendering without the SRE dependency, but still want speech accessibility on the client.
+
+### Prerequisites
+
+The rendered HTML must include `<mjx-assistive-mml>` elements (i.e., the server used `accessibility: { assistiveMml: true }`).
+
+### Loading the script
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/mathpix-markdown-it@latest/es5/browser/add-speech.js"></script>
+```
+
+By default, the script automatically processes `document.body` on `DOMContentLoaded`.
+
+### Usage
+
+```js
+// Add speech to all rendered math in a specific container
+window.MathpixSpeech.addSpeechToRenderedMath(document.getElementById('content'));
+```
+
+### Configuration
+
+Set `window.MathpixSpeechConfig` before the script loads to customize behavior:
+
+```js
+window.MathpixSpeechConfig = {
+  container: document.getElementById('math-content') // defaults to document.body
+};
+```
+
+### What it does
+
+For each `mjx-container` element that does not already have an `aria-label`:
+1. Extracts MathML from the `<mjx-assistive-mml>` child element
+2. Generates speech text using SRE (Speech Rule Engine)
+3. Sets `aria-label`, `role="math"`, and `tabindex="0"` on the container
+
+
 # Documentation
 
 ## React components
@@ -733,10 +854,12 @@ The `MathpixMarkdown` React element accepts the following props:
 |                                                    | returns | description                                                                                                               |         |
 |----------------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------|---------|
 | **Style methods:**                                 |         |                                                                                                                           |         |
+| buildStyles(opts?: [StyleBundleOpts](https://github.com/Mathpix/mathpix-markdown-it#stylebundleopts)) | string | Single CSS builder. All style assembly methods delegate here. Modules toggled via opts.                                   |         |
 | loadMathJax()                                      | boolean | Adds a style element into the head of the document and returns true. In case of an error, returns false.                  |[example](https://github.com/Mathpix/mathpix-markdown-it/tree/master/examples/react-app/use-markdownToHTML-method)|
-| getMathpixStyleOnly()                              | string  | returns styles as a string.                                                                                               |         |
-| getMathpixStyle(true)                              | string  | returns styles as a string including styles for container.                                                                |[example](https://github.com/Mathpix/mathpix-markdown-it/tree/master/examples/react-app/use-render-method)|
-| getMathpixFontsStyle()                             | boolean | returns fonts styles as a string.                                                                                         |[example](https://github.com/Mathpix/mathpix-markdown-it/tree/master/examples/react-app/use-render-method)|
+| getMathpixStyleOnly(useColors?)                     | string  | Styles for embedded widget (no container/preview).                                                                        |         |
+| getMathpixStyle(stylePreview?, showToc?, tocContainerName?, useColors?, isPptx?) | string | Full page styles including container.                                                                                     |[example](https://github.com/Mathpix/mathpix-markdown-it/tree/master/examples/react-app/use-render-method)|
+| getMathpixFontsStyle()                             | string  | Returns fonts styles as a string.                                                                                         |[example](https://github.com/Mathpix/mathpix-markdown-it/tree/master/examples/react-app/use-render-method)|
+| getMaxWidthStyle(maxWidth?, isHideScroll?)         | string  | Returns CSS for math/tabular max-width constraints and optional scrollbar hiding.                                         |         |
 | **Render methods:**                                |         |                                                                                                                           |         |
 | markdownToHTML(str, options: [TMarkdownItOptions](https://github.com/Mathpix/mathpix-markdown-it#tmarkdownitoptions)) | string  | Renders input text to html element as a string.                                                                           |[example](https://github.com/Mathpix/mathpix-markdown-it/tree/master/examples/react-app/use-markdownToHTML-method)|
 | render(str, options: [optionsMathpixMarkdown](https://github.com/Mathpix/mathpix-markdown-it#optionsmathpixmarkdown))     | string  | Renders input text to  HTML element as a string and wraps it in a container. Should be used to render the entire document.|[example](https://github.com/Mathpix/mathpix-markdown-it/tree/master/examples/react-app/use-render-method)|
@@ -746,6 +869,24 @@ The `MathpixMarkdown` React element accepts the following props:
 
 
 
+### StyleBundleOpts
+
+|                          | type&nbsp;*`default`*         | description                                                |
+|--------------------------|-------------------------------|------------------------------------------------------------|
+| `setTextAlignJustify`    | boolean&nbsp;*`false`*        | Enables `text-align: justify` on content blocks            |
+| `useColors`              | boolean&nbsp;*`true`*         | When `false`, omits color declarations from CSS output     |
+| `maxWidth`               | string&nbsp;*`''`*            | Sets max-width for math/tabular containers (e.g. `'800px'`)|
+| `isPptx`                 | boolean&nbsp;*`false`*        | Adjusts layout for PowerPoint export                       |
+| `resetBody`              | boolean&nbsp;*`false`*        | Includes body margin/line-height reset                     |
+| `container`              | boolean&nbsp;*`false`*        | Includes base element styles (headings, links, tables etc) |
+| `mathjax`                | boolean&nbsp;*`false`*        | Includes MathJax stylesheet                                |
+| `code`                   | boolean&nbsp;*`true`*         | Includes syntax-highlighting styles                        |
+| `preview`                | boolean&nbsp;*`false`*        | Includes `#preview` wrapper styles                         |
+| `toc`                    | boolean&nbsp;*`false`*        | Includes table-of-contents styles                          |
+| `tocContainerName`       | string&nbsp;*`'toc'`*        | ID of the TOC container element                            |
+| `menu`                   | boolean&nbsp;*`false`*        | Includes context-menu and clipboard styles                 |
+
+
 ### TMarkdownItOptions
 
 |                                       | type&nbsp;*`default`*        |  description                                                                                                           |
@@ -818,6 +959,7 @@ The `MathpixMarkdown` React element accepts the following props:
 
 |                          | type&nbsp;*`default`*        |  description                                                                                                      |
 |--------------------------|------------------------------|-------------------------------------------------------------------------------------------------------------------|
+| `output_format`          | `'svg' \| 'mathml' \| 'latex'`&nbsp;*`'svg'`* | Controls which math format is placed in HTML output. See [Output Format](#output-format) section.    |
 | `include_mathml`         | boolean&nbsp;*`false`*       | outputs mathml `<mathml style="display: none"><math>...</math></mathml>`                                          |
 | `include_mathml_word`    | boolean&nbsp;*`false`*       | outputs mathml_word `<mathmlword style="display: none"><math>...</math></mathmlword>`                             |
 | `include_asciimath`      | boolean&nbsp;*`false`*       | outputs asciimath `<asciimath style="display: none">...</asciimath>`                                              |
@@ -964,7 +1106,7 @@ const { loadSreAsync } = require('mathpix-markdown-it/lib/sre/sre-node');
 
 ```
 
-Then just pass the resulting value to `accessibility.spe`
+Then just pass the resulting value to `accessibility.sre`
 ```js
 accessibility: {
      assistiveMml: true, // assistive-mml will be added to mjx-container

package/doc/changelog.md

@@ -1,5 +1,69 @@
+# March 2026
+
+## [2.0.37] - CSS scoping and style module cleanup
+
+- CSS Scoping:
+  - All MMD class selectors now have `#preview-content`/`#setText` scoped variants for specificity boost.
+  - Bare selectors preserved as fallback for `markdownToHTML()` (no wrapper).
+
+- Style Architecture:
+  - New `buildStyles(opts: StyleBundleOpts)` single CSS builder — all assembly methods delegate here.
+  - `MathpixStyle` restructured into 10 composable sub-functions.
+  - Color constants extracted into `src/styles/colors.ts`.
+  - `halpers.ts` renamed to `helpers.ts`.
+
+- Improvements:
+  - `.tabular` now renders consistently regardless of context (standalone vs nested inside a list). Previously, list context could affect table width and font size via cascade. Fixed with explicit `margin: 0 0 1em`, `font-size: inherit`, and other defensive defaults.
+  - `useColors=false` now correctly omits blockquote border, table border, and mark background colors.
+  - `getMathpixStyle(useColors=false)` now also omits `ContainerStyle` colors (body text, headings, links, captions). Previously `ContainerStyle()` was always called with default colors.
+
+- Bug Fixes:
+  - `div.svg-container` child combinator consistency (`>` for both `#preview-content` and `#setText`).
+  - `loadMathJax` updates existing `#Mathpix-styles` element instead of skipping.
+
+- Breaking Changes:
+  - `scaleEquation` parameter removed from `loadMathJax`, `getMathpixStyleOnly`, `getMathpixStyle`, and `getMathpixMarkdownStyles`. It was never used in CSS output. If you were passing it positionally, shift your arguments. Use `buildStyles(opts)` for a named-parameter alternative.
+
+- Dead Code Removed:
+  - `.empty` selector (never generated), `.preview-right` selector (used as id, not class).
+
+- Docs:
+  - Added implementation details in `pr-specs/2026-03-mmd-css-scoping.md`.
+
 # February 2026
 
+## [2.0.36] - 16 February 2026
+
+- Math Output Format:
+  - Added `output_format` option to `TOutputMath` to control which math format is placed in HTML output.
+  - `'svg'` (default): Pre-rendered SVG with hidden formats, works offline.
+  - `'mathml'`: Native `<math>` elements only, smaller file size, requires client-side rendering.
+  - `'latex'`: Raw LaTeX with original delimiters, smaller file size, requires client-side rendering.
+
+- Browser Rendering Script (`auto-render.js`):
+  - New browser bundle for client-side math rendering at `es5/browser/auto-render.js`.
+  - Renders MathML or LaTeX content to SVG.
+  - Generates hidden format elements for context menu compatibility.
+  - Configurable accessibility support via `MathpixAccessibilityConfig`:
+    - `assistive_mml`: Add `<mjx-assistive-mml>` for screen readers.
+    - `include_speech`: Add `aria-label` with speech text.
+
+- Browser Speech Script (`add-speech.js`):
+  - New browser bundle for adding speech to already-rendered SVG at `es5/browser/add-speech.js`.
+  - Use when SVG was rendered with `assistiveMml: true` but without `sre` (speech).
+  - Loads SRE dynamically and adds `aria-label`, `role="math"`, `tabindex` to `mjx-container` elements.
+  - Requires `mjx-assistive-mml` to be present in the rendered output.
+  - Exposes `window.MathpixSpeech.addSpeechToRenderedMath(container?)`.
+
+- Accessibility:
+  - `mjx-assistive-mml` is no longer marked with `aria-hidden="true"` when accessibility options are enabled. Previously, the assistive MathML element was hidden from screen readers even when the user explicitly requested accessibility via `assistiveMml: true` or `sre`. Now, if any accessibility option is set, the MathML content is exposed to assistive technology — either via `aria-labelledby` (pointing to the assistive MML) or via `aria-label` (SRE speech text). This affects both server-side rendering (`addAriaToMathHTML`) and the new browser bundles.
+
+- Fixes:
+  - Fixed centering issue for equations with numbering inside `.math-block[data-width="full"]`.
+
+- Docs:
+  - Added implementation details in `pr-specs/2026-01-html-math-output-options.md`.
+
 ## [2.0.35] - 13 February 2026
 
 - Tabular: