docmd provides a robust, multi-layered security model to protect static sites against Cross-Site Scripting (XSS), malicious third-party embeds, and unintended raw HTML injection.

Security Configuration Schema

Security rules can be configured in your docmd.config.json manifest:

docmd.config.json
{
  "security": {
    "htmlPolicy": "escape",
    "strictLinkSanitizing": true,
    "allowedIframeHosts": [
      "youtube.com",
      "vimeo.com",
      "codesandbox.io",
      "stackblitz.com"
    ]
  }
}

HTML Processing Policies (htmlPolicy)

The htmlPolicy setting controls how docmd processes raw HTML elements declared inside Markdown files:

Mode Behaviour Best Use Case
"escape" (Default) Converts all raw HTML tags into safe HTML entities (<div>). Prevents accidental script injection. Public documentation sites and open open-source repositories accepting pull requests from untrusted contributors.
"strip" Completely strips raw HTML tags from the compiled output. Strict corporate sites requiring plain text markdown purity without raw tags.
"allow" Renders raw HTML elements as executable DOM nodes. Authoritative technical docs incorporating custom web components or unstyled raw HTML (noStyle: true).
XSS Caution with htmlPolicy: ‘allow’

Setting htmlPolicy to "allow" enables arbitrary script execution if Markdown files contain <script> tags. Use "allow" only when Markdown content originates from trusted source code repositories.

Multi-Line HTML Block Handling

In docmd, raw HTML blocks are processed without breaking when blank lines exist inside elements:

<div class="custom-widget">
    <h3>Widget Title</h3>

    <p>Paragraph with blank lines surrounding it.</p>
</div>

When htmlPolicy is set to "allow", docmd preserves the outer block hierarchy and prevents markdown-it from corrupting inner tags into indented code blocks or plain text paragraphs.

All external hyper-references generated by docmd containers (::: tag, ::: button, ::: card) and Markdown links ([text](https://...)) are sanitized automatically:

<a href="https://external-site.com" target="_blank" rel="noopener noreferrer">External Link</a>
  • target="_blank" ensures external links open in a separate browser tab.
  • rel="noopener noreferrer" prevents the destination page from obtaining window.opener control or accessing session storage.

Embed & Iframe Sandboxing

The ::: embed container relies on embed-lite to transform video and widget URLs into sandboxed <iframe> wrappers:

::: embed https://www.youtube.com/watch?v=dQw4w9WgXcQ # trusted video embed

Sandboxed iframes restrict top-level navigation, form submissions, and direct parent DOM manipulation by default while preserving media playback capability.

Next Overview