Markdown syntax

Who renders your Markdown?

The Better Doctor Markdown custom web part renders your prepared content on SharePoint Online. It replaces the built-in Markdown control as Better Doctor’s publishing target. Follow the deployment and migration guide before upgrading existing sites; browser and tenant pilot checks remain required before rollout.

By default, Better Doctor publishes prepared Markdown. With markdown.allowHtml, the CLI also runs shortcodes and prepares HTML compatibility content. Both paths use the custom web part’s sanitization and enhancement pipeline. Front matter is metadata, not visible page content.

Code highlighting and copy

Fenced code blocks support syntax highlighting and a copy action. Copy uses the original code source, not toolbar labels or decorated HTML. If the browser denies clipboard access, use the displayed source to copy manually.

```typescript
const message = "Documentation stays in the repository";
```

markdown.theme selects Dark (default) or Light code colors. It is separate from the SharePoint page/section theme, which supplies surrounding text, surface, and link colors.

Mermaid diagrams

Use a fenced mermaid block without enabling raw HTML:

```mermaid
flowchart LR
    A[Repository] --> B[Better Doctor] --> C[SharePoint]
```

The web part renders diagrams in the browser using its bundled Mermaid version, not SharePoint’s built-in renderer or a publish-time image upload. Existing <mermaid> shortcodes remain available with allowHtml: true.

Extended syntax

The existing allowHtml gate remains: enable it to use extended syntax and shortcodes. extended defaults to true within that path:

{
  "markdown": {
    "allowHtml": true,
    "extended": true
  }
}

Set extended to false to turn off these extra Markdown plugins.

Emoji

:pushpin: Purpose and :pencil2: Definition

Highlighted text

This is ==highlighted== text.

Footnotes

Here is a footnote reference[^1]

[^1]: And here is the footnote itself.

Definition lists

Term
: The definition of the term

Task lists

- [x] Write the documentation
- [ ] Publish the documentation

Math and LaTeX

Math rendering is off by default. Enable it with a JSON boolean:

{
  "markdown": {
    "enableMath": true
  }
}

Or override the setting for a run:

bdoctor publish --enableMath true
bdoctor publish --enableMath false

The explicit CLI value wins over bdoctor.json; false disables math even if the configuration says true. A bare --enableMath or a value other than true or false is invalid. Math does not require allowHtml.

With math enabled, use $...$ for inline math and $$...$$ for a display block:

The relation is $E = mc^2$.

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

• Escape a literal dollar sign as \$ when math is enabled.
• Inline delimiters must enclose an expression; avoid whitespace immediately inside the opening or closing $.
• Math inside inline code or fenced code stays code. Ordinary currency should stay literal; escape dollar signs in ambiguous prose such as multiple prices.
• With math disabled, $...$ and $$...$$ remain literal Markdown text.

The web part loads its packaged KaTeX renderer and matching fonts/styles. It uses untrusted-input restrictions, not executable TeX commands. Invalid or unsupported expressions need correction in source; inspect the rendering error/source rather than assuming every LaTeX command is supported. Verify formulas and accessible output in the deployed pilot.

HTML and preview boundaries

Allowed HTML and shortcode output are sanitized. Scripts, unsafe URLs, event handlers, and arbitrary author styles are not supported. CSS belongs to the scoped web part bundle rather than the published payload.

In SharePoint edit mode, Monaco offers temporary prepared-Markdown preview and export only. It does not save to repository files or Better Doctor-managed content. HTML compatibility content supports read-only inspection/export. Expanded partials and rewritten links in an export are not the original source files. Make permanent changes in the repository and publish again.

Syntax overview

Syntax	Default prepared Markdown	With allowHtml: true
Headings, emphasis, lists, links, images, tables	Yes	Yes
Code highlighting and copy	Yes	Yes
Fenced Mermaid	Yes	Yes
Table of contents	No automatic TOC	Via the toc shortcode
Author HTML	No	Sanitized
Shortcodes	No	Publish-time
Emoji, marks, footnotes, definitions, task lists	No	With extended
KaTeX math	With enableMath: true	With enableMath: true