Shortcodes

Shortcodes are HTML snippets inside your content files calling built-in or custom templates. You can use these shortcodes like custom HTML elements. Similar like custom web components.

Important

Shortcodes require markdown.allowHtml: true. Better Doctor runs them in the CLI and publishes HTML compatibility content to the custom Better Doctor Markdown web part. That content is read-only in the browser inspection/export view. Make permanent changes in the repository and publish again.

Better Doctor has built-in shortcodes, but also supports you to create your own shortcodes. If you are missing something, or have a special requirement, this will allow you to make it possible.

At the moment, bdoctor has the following built-in shortcodes:

• Callout
• Icon
• Mermaid
• Table of contents

Provide your own shortcodes

You can add custom shortcodes to your project by adding a JavaScript file to the shortcodes folder (If you want, you can change this location - Markdown publishing settings). The contents of the JavaScript file should contain the following:

ES module syntax (use this when your package.json contains "type": "module"):

// Usage in Markdown: <shortcode-name name="name attribute">the content</shortcode-name>
export default {
  name: "shortcode-name",
  render: (attributes, html) => {
    return `<div>Name: ${attributes.name} - HTML: ${html}</div>`;
  },
  beforeMarkdown: false,
};

CommonJS syntax (use this when your package.json does not contain "type": "module", or rename your file to .cjs):

// Usage in Markdown: <shortcode-name name="name attribute">the content</shortcode-name>
module.exports = {
  name: "shortcode-name",
  render: (attributes, html) => {
    return `<div>Name: ${attributes.name} - HTML: ${html}</div>`;
  },
  beforeMarkdown: false,
};

Note

If your project uses "type": "module" in package.json and you want to keep CommonJS syntax, rename your shortcode file from .js to .cjs.

beforeMarkdown : This is an optional property introduced to specify if you want to parse the shortcode before or after the Markdown gets processed. In case you include your own Markdown code with your shortcode, you can set this property to true. Otherwise you keep ot set to false or do not include it.

Output and preview boundaries

The before/after Markdown phases and local .js/.cjs loading remain CLI responsibilities. The browser does not load these modules or resolve local include files. Newly typed custom shortcodes in a preview need a Better Doctor publish to execute; exporting a preview does not write back to source.

Shortcode output is sanitized in the custom web part. Supported callouts, icons, TOC, links, and tables remain part of the compatibility path; scripts, event handlers, unsafe URLs, and arbitrary author CSS are not. The published payload contains no inline CSS; styling belongs to the web part’s scoped bundle. Review custom shortcodes against this boundary in the deployment pilot.

The Mermaid shortcode now emits inert source for browser rendering instead of an uploaded SVG image.