Configuration
Security

Security & HTML Policy

docmd provides a 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": {
    "html": "allow",
    "strictLinkSanitizing": true,
    "allowedIframeHosts": [
      "youtube.com",
      "vimeo.com",
      "codesandbox.io",
      "stackblitz.com"
    ]
  }
}

Backwards Compatibility

Earlier docmd releases configured HTML processing policies using "htmlPolicy" inside "security" or at the root level. Both "security.htmlPolicy" and root "htmlPolicy" continue to be automatically mapped to "security.html" for full backward compatibility.

HTML Processing Policy (`security.html`)

The security.html setting controls how docmd processes raw HTML elements declared inside Markdown files:

Mode	Behaviour	Best Use Case
`"allow"` (Default)	Renders raw HTML elements as executable DOM nodes.	Authoritative technical docs incorporating custom web components or unstyled raw HTML (`noStyle: true`).
`"escape"`	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.

XSS Caution with html: ‘allow’

Setting html 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.

External Link Isolation

All external hyper-references generated by docmd containers (::: tag, ::: button, ::: card) and Markdown links ([text](https://...)) are sanitised 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.

Last updated: Edit this page