Preface¶

When using Pandoc-style $$ to display math blocks in the DSH Web client, parsing errors can occur. This can cause the first line of a formula to be silently discarded, or from the second line to the end of the message to be swallowed, ultimately resulting in a red KaTeX error. These formats render normally in other Markdown renderers (such as VS Code).

What is this¶

This is a DSH Web client plugin maintained by s11phere. Its core purpose is to fix the issue where DSH’s Markdown parser incorrectly parses Pandoc-style $$ math blocks: it resolves the problem of the first line being silently discarded, or the remainder of the message being swallowed and displayed as an error. It normalizes non-standard math block shapes into a standard shape.

Installation and enablement¶

Use the following command to add the plugin to the DSH Web configuration:

dsh plugin --profile web add <本包目录>

After running the command, restart dsh web and refresh the page to apply the changes.

Core features¶

1. Fix parsing errors: Adjusts syntax that previously caused the first line to be silently discarded or the rest of the message to be swallowed into a format that DSH can correctly recognize.
2. Normalize shapes: Unifies non-standard math block shapes (such as starting with $$内容, or ending with $$ on its own line) into the standard shape ($$ on its own line, content on its own line, $$ on its own line).
3. Repair historical messages: Supports re-rendering and repairing historical messages already recorded in a session. This process does not modify session data.
4. Temporary disablement: Supports temporarily disabling the plugin via an environment variable.

Typical usage¶

Standard shape example:

$$\n独占一行\n$$

Display math example:

$$\n\\frac{\\partial}{\\partial y} = 1\n\\quad\\Longrightarrow\\quad\n x = y$$

Verification and debugging¶

After installation, you can verify that the plugin is working correctly in the following ways:

1. Console log: After refreshing the page, the following log should appear in the browser console: [dsh-tex-block-normalizer] active: Pandoc-style $$ blocks are normalized before Markdown parsing.
2. Debug object: In the browser console, inspect window.__DSH_TEX_BLOCK_NORMALIZER__. Its content should include { installed: true, reason: 'installed', stats: { calls, rewrites } }. An increase in the rewrites value indicates that a rewrite occurred.
3. Historical message repair: Open a historical message that previously displayed a red error. The error should disappear, and the formula should render correctly.
4. Temporary disablement: Set globalThis.__DSH_TEX_BLOCK_NORMALIZER_DISABLE__ = true before the page loads to temporarily disable the plugin.

Use cases and notes¶

This plugin is suitable for scenarios where Pandoc-style math formulas need to be used correctly in the DSH Web client.

Notes:
* It does not handle $$ inside blockquotes (> $$) or list items (- $$).
* Blocks without a closing $$ are left unchanged and will therefore still be swallowed to the end of the file.
* The plugin requires Node.js >= 22.5.
* The plugin depends on the external library @deepseek-ai/dsh-client-ui-primitives.

Conclusion¶

The plugin resolves parsing deficiencies in DSH’s handling of specific math block formats through simple text rewriting. For developers encountering formula display issues, this is a low-intrusion solution. For detailed documentation and source code, refer to the links below.