This is an extension of the Diplodoc platform, which allows embedding HTML via Markdown directives.
This file contains info on the following topics:
- Embedding strategies supported by the extension
- Recommendations on
isolated
strategy usage to make sure you can embed potentially unsafe content in a safe way - Docs for browser runtime, this extension's component which is responsible for properly displaying the embedded content in browser.
- Docs for MarkdownIt transform plugin, which was specifically tailored for use with
@diplodoc-platform/transform
. It ensures the embedding syntax can be rendered as HTML. - Docs for React hooks
This plugin uses the container block directive syntax. For more information see here: diplodoc-platform/directive.
Simple example:
::: html
<div>Your HTML code is here</div>
:::
Example with some styles:
::: html
<style>
:root {
--dark-bg-color: #000;
--dark-text-color: #FFF;
}
.dark {
background-color: var(--primary-bg-color);
color: : var(--primary-text-color);
}
</style>
<div class="dark">Some info is here</div>
:::
Attach the plugin to the transformer:
import htmlExtension from '@diplodoc/html-extension';
import transform from '@diplodoc/transform';
import * as sanitizeHtml from 'sanitize-html';
const {result} = await transform(
`
::: html
<article class="forecast">
<h1>Weather forecast for Seattle</h1>
<article class="day-forecast">
<h2>12 June 2024</h2>
<p>Rain.</p>
</article>
<article class="day-forecast">
<h2>13 June 2024</h2>
<p>Periods of rain.</p>
</article>
<article class="day-forecast">
<h2>14 June 2024</h2>
<p>Heavy rain.</p>
</article>
</article>
:::
`,
{
plugins: [
htmlExtension.transform({
sanitize: (dirtyHtml) =>
sanitizeHtml(dirtyHtml, {
allowedTags: ['article', 'h1', 'h2', 'p', 'span'],
allowedAttributes: {
'*': ['class'],
},
}),
containerClasses: 'my-own-class',
}),
],
},
);
The extension supports three different embedding strategies:
-
srcdoc
— Uses an IFrame withsrcdoc
attribute to embed specified HTML. As such, the IFrame inherits parent's origin andContent-Security-Policy
. However, all CSS is isolated by default and there can never be any style leakage. Depending on the CSP used, this mode introduces a potential attack vector, since arbitrary JS code could have been allowed to be run by host's CSP. As such, use of sanitization is strongly preferred when using this mode (see below in plugin documentation). -
shadow
— Currently an experimental strategy that uses a ShadowRoot to embed content into the host page. Very similar in application and effects tosrcdoc
, but uses less runtime logic in browser, providing a more smooth experience (eliminates height resize jitters, etc.). Content sanitization is still strongly recommended. Styles declared inside of the ShadowRoot are isolated from the rest of the page as per ShadowDOM rules, and potential inheritable global styles are isolated viaall: initial
at Shadow DOM boundary. -
isolated
— A strategy that uses a special IFrame that should be hosted on a separate origin such that Same-Origin-Policy (SOP) would not apply for this IFrame. By opting-out of SOP, any scripts that are being run inside of the IFrame cannot get access to parent's execution context, as well as its storage, cookies and more. Crucially, this mode also provides an option to use a less restrictive CSP for content inside trhe IFrame. As such, this strategy is ideal for widget embedding (or other types of potentially unsafe content).Please note that while one could enforce SOP failure by providing
srcdoc
IFrame withsandbox
attribute, the only way to override parent's (host's) CSP to a less restrictive set of policies would be to physically host an IFrame on a different origin.Due to high level of isolation, sanitization is not required. Moreover, this mode/strategy was specifically designed to work with unsanitized/unrestricted content, and as such,
sanitize
option of this extension's MarkdownIt plugin explicitly has no effect when using this mode.
While srcdoc
and shadow
modes require no further minimal setup other than including the runtime and using the plugin, isolated
mode requires you to have a thin isolated
-compatible IFrame runtime hosted somewhere on a separate origin.
The IFrame runtime which contains the code necessary to communicate with the host's runtime is exposed as the @diplodoc-platform/html-extension/iframe
export. This file can then be hosted in a multitude of ways:
- Use a CDN, since most CDNs' origins are not designed to host full web apps, and as such, these origins shouldn't have vital cookies, storage or other critical data associated with them, minimizing and/or effectively nullifying the potential harm that could be done when some malicious code is being run in the embed.
- Set up a different reverse proxy/HTTP server/L7 upstream that responds to a different
host
header/:authority
pseudo-header.
Make sure not to use any subdomains of the app, since this way cookies could still get exposed to malicious code.
It is necessary to add runtime
scripts to make embeds interactive on your page.
You can add assets files which were generated by the MarkdownIt transform plugin.
<html>
<head>
<!-- Read more about '_assets/html-extension.js' and '_assets/html-extension.css' in 'Transform plugin' section -->
<script src="_assets/html-extension.js" async></script>
</head>
<body>
${result.html}
</body>
</html>
Or you can just include runtime's source code in your bundle.
import '@diplodoc/html-extension/runtime';
Plugin for @diplodoc/transform package.
Options:
-
runtimeJsPath
- name on runtime script which will be exposed in resultsscript
section.
Default:_assets/html-extension.js
-
bundle
- boolean flag to enable/disable copying of bundled runtime to target directory.
Where target directore is<transformer output option>/<plugin runtime option>
Default:true
-
containerClasses
- additional classes which will be added to tab's container node. It allows to customize the html view.
Example:my-own-class and-other-class
Default:undefined
-
embeddingMode
- embedding strategy which should be used for all encountered embeds.Accepted values:
srcdoc
,shadow
,isolated
.Default:
srcdoc
. -
isolatedSandboxHost
- fully-qualified URL of the IFrame runtime used specifically byisolated
mode. Has no effect when other modes are used. This can still be overriden byEmbedsConfig.isolatedSandboxHostURIOverride
viaEmbeddedContentRootController.initialize
andEmbeddedContentRootController.setConfig
. -
sanitize
- optional function that will be used to sanitize content insrcdoc
andshadow
modes if supplied.
You can use the React hook to interact programmatically with the HTML content inside the block.
// TODO