Redirected from /superdoc-dev/superdoc
SuperDoc

https://github.com/superdoc/docx-editor
Admin
SuperDoc is a collaborative document engine and editor for DOCX files that renders, edits, and...
Tokens:5,274
Snippets:84
Trust Score:7.5
License:AGPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install SuperDoc Extension via Command Line

Source: https://github.com/superdoc/docx-editor/blob/main/apps/vscode-ext/README.md

Use this command in the VS Code Quick Open menu or terminal to install the extension.

```bash
ext install superdoc-dev.superdoc-vscode-ext
```

--------------------------------

### Create a new converter file

Source: https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/painters/dom/src/features/math/CONTRIBUTING.md

Example implementation for a superscript converter.

```typescript
import type { MathObjectConverter } from '../types.js';

const MATHML_NS = 'http://www.w3.org/1998/Math/MathML';

export const convertSuperscript: MathObjectConverter = (node, doc, convertChildren) => {
  const elements = node.elements ?? [];
  const base = elements.find((e) => e.name === 'm:e');
  const sup = elements.find((e) => e.name === 'm:sup');

  const msup = doc.createElementNS(MATHML_NS, 'msup');
  msup.appendChild(convertChildren(base?.elements ?? []));
  msup.appendChild(convertChildren(sup?.elements ?? []));

  return msup;
};
```

--------------------------------

### Register in the registry

Source: https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/painters/dom/src/features/math/CONTRIBUTING.md

Import and register the new converter in the main registry file.

```typescript
// Add to imports
import { convertMathRun, convertFraction, convertSuperscript } from './converters/index.js';

// Change null → your converter in the registry
'm:sSup': convertSuperscript,  // was: null
```

--------------------------------

### Implement a fraction converter

Source: https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/painters/dom/src/features/math/CONTRIBUTING.md

Reference implementation for converting OMML fraction elements to MathML.

```typescript
import type { MathObjectConverter } from '../types.js';

const MATHML_NS = 'http://www.w3.org/1998/Math/MathML';

export const convertFraction: MathObjectConverter = (node, doc, convertChildren) => {
  const elements = node.elements ?? [];

  // 1. Find the OMML child elements you need
  const num = elements.find((e) => e.name === 'm:num');
  const den = elements.find((e) => e.name === 'm:den');

  // 2. Create the MathML element
  const frac = doc.createElementNS(MATHML_NS, 'mfrac');

  // 3. Convert children recursively and append
  frac.appendChild(convertChildren(num?.elements ?? []));
  frac.appendChild(convertChildren(den?.elements ?? []));

  return frac;
};
```

--------------------------------

### Add a unit test

Source: https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/painters/dom/src/features/math/CONTRIBUTING.md

Verify the converter logic with a test case.

```typescript
it('converts m:sSup to <msup>', () => {
  const omml = {
    name: 'm:oMath',
    elements: [
      {
        name: 'm:sSup',
        elements: [
          { name: 'm:e', elements: [{ name: 'm:r', elements: [{ name: 'm:t', elements: [{ type: 'text', text: 'x' }] }] }] },
          { name: 'm:sup', elements: [{ name: 'm:r', elements: [{ name: 'm:t', elements: [{ type: 'text', text: '2' }] }] }] },
        ],
      },
    ],
  };

  const result = convertOmmlToMathml(omml, doc);
  expect(result).not.toBeNull();

  const msup = result!.querySelector('msup');
  expect(msup).not.toBeNull();
  expect(msup!.children.length).toBe(2);
  expect(msup!.children[0]!.textContent).toBe('x');
  expect(msup!.children[1]!.textContent).toBe('2');
});
```

--------------------------------

### Export from barrel file

Source: https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/painters/dom/src/features/math/CONTRIBUTING.md

Add the new converter to the index file.

```typescript
export { convertMathRun } from './math-run.js';
export { convertFraction } from './fraction.js';
export { convertSuperscript } from './superscript.js';  // ← add this
```

--------------------------------

### Math Feature Directory Structure

Source: https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/painters/dom/src/features/math/CONTRIBUTING.md

File organization for the math conversion logic within the layout-engine package.

```text
packages/layout-engine/painters/dom/src/features/math/
├── CONTRIBUTING.md          ← you are here
├── types.ts                 ← OmmlJsonNode, MathObjectConverter types
├── omml-to-mathml.ts        ← registry + core converter
├── omml-to-mathml.test.ts   ← tests
└── converters/
    ├── index.ts             ← barrel exports
    ├── math-run.ts          ← m:r → <mi>/<mo>/<mn> (leaf nodes)
    └── fraction.ts          ← m:f → <mfrac> (reference implementation)
```

--------------------------------

### Accessing Math Properties

Source: https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/painters/dom/src/features/math/CONTRIBUTING.md

Use the find method on the elements array to locate specific property elements like m:radPr.

```javascript
elements.find(e => e.name === 'm:radPr')
```

--------------------------------

### Update base_id selection logic

Source: https://github.com/superdoc/docx-editor/wiki/.pr_agent_accepted_suggestions

Replace truthiness-based fallback with explicit None-checks to ensure empty strings are not treated as missing values.

```python
base_id = input.get('base') or input.get('preset') or 'core'
```

```python
base_arg = input.get('base')
preset_arg = input.get('preset')
base_id = base_arg if base_arg is not None else (preset_arg if preset_arg is not None else 'core')
```

--------------------------------

### OMML Object Pattern

Source: https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/painters/dom/src/features/math/CONTRIBUTING.md

Standard structure for OMML math objects where property elements are skipped and argument elements are processed.

```xml
<m:OBJECT_NAME>
  <m:OBJECT_NAMEPr>   <!-- Properties (optional) — skipped automatically -->
    ...
  </m:OBJECT_NAMEPr>
  <m:ARGUMENT_1>       <!-- Named child elements containing math content -->
    <m:r><m:t>...</m:t></m:r>
  </m:ARGUMENT_1>
  <m:ARGUMENT_2>
    ...
  </m:ARGUMENT_2>
</m:OBJECT_NAME>
```

--------------------------------

### Define the MathObjectConverter interface

Source: https://github.com/superdoc/docx-editor/blob/main/packages/layout-engine/painters/dom/src/features/math/CONTRIBUTING.md

The standard signature for all math object converters, requiring the node, document, and a recursive child conversion function.

```typescript
type MathObjectConverter = (
  node: OmmlJsonNode,       // The OMML element (e.g., an m:sSup node)
  doc: Document,            // For creating DOM elements
  convertChildren: (children: OmmlJsonNode[]) => DocumentFragment,
                             // Recursively converts nested OMML content
) => Node | null;           // Return a single Element for one atom, or a
                             // DocumentFragment when your converter produces
                             // multiple sibling elements (see m:r / math-run).
```
Tokens:
Raw