Mermaid

The Better Doctor Markdown custom web part draws Mermaid diagrams in the browser, using its bundled Mermaid version. Deploy the matching SPFx solution before publishing pages.

Fenced diagrams

Fenced Mermaid works without enabling markdown.allowHtml:

```mermaid
flowchart LR
    A[Write Markdown] --> B[Publish with Better Doctor]
    B --> C[View on SharePoint]
```

Existing shortcode syntax

With markdown.allowHtml: true, keep using the <mermaid> shortcode. Use alt to describe the diagram:

<mermaid alt="Documentation moves from the repository to SharePoint">
flowchart LR
    A[Repository] --> B[SharePoint]
</mermaid>

As this shortcode is parsed as HTML, write < instead of < inside the definition. Fenced diagrams avoid that HTML encoding requirement.

Rendering and errors

Better Doctor publishes inert diagram source rather than a finished SVG image. The web part loads Mermaid when needed and renders inside its own instance. It does not upload new diagram SVGs to the asset library, inject public CDN scripts, or hand unsupported types to SharePoint’s own Mermaid renderer. Existing asset-library images are not a migration backup and need not be manually deleted to enable browser rendering.

The old headless renderer’s restrictions on browser-dependent diagrams such as mindmap, C4Context, and block-beta no longer define this rendering path. Actual support depends on the bundled Mermaid version and strict sanitization. Include your diagram types in the required browser/tenant pilot; not every type, layout, or style combination has been verified on SharePoint.

Diagrams use strict security settings. Executable callbacks and arbitrary external loads are not supported. Custom Mermaid styling is subject to the renderer and SVG sanitization policy; do not rely on it to style other controls. The web part’s scoped presentation follows the host theme.

Syntax errors are handled in the browser with an error/source view. A successful CLI publish is therefore not evidence that a diagram rendered successfully. Review the deployed page, fix the source, and publish again.