Provide `@Embed` directive as an equivalent of HTML <embed/> or <iframe/>

[edudnyk]

Feature Name

@Embed directive

Description

Provide an equivalent of HTML <embed/> element as a directive that can be used in markdown files and code-level documentation:

@Embed("https://host.com/embedded-content")

DocC should throw an error if malformed URL string is provided as an argument.
The directive should be rendered as <embed src="https://host.com/embedded-content"/> or <iframe src="https://host.com/embedded-content"/> in the resulting web document.

The type argument of the <embed/> HTML element which is a MIME-type of the content, can be omitted.
There is the customization of the frame possible through width and height parameters of the <embed/> or <iframe/> HTML elements, however, there is no need to support them as explicit arguments of the @Embed directive since there is an experimental device frame support which can serve as a themable source of the @Embed's size.

Related thread on Swift Forums can be found here.

Motivation

• Embedding of Figma external designs,
• Embedding of YouTube videos,
• Embedding of any other web content that is embeddable.

Importance

There is currently no way to embed web embeddable content into DocC documentation.
This feature will unlock entirely new dimensions of cross-referencing between different environments and audiences.

Alternatives Considered

As an alternative, there is a possibility to render @Embed directive as <iframe/> HTML element instead of <embed/>, the final choice should be made considering the following:

• With <embed/> it's possible to get the context of the child from the parent and vice versa. This means that it's possible to use scripts in the parent to manipulate the child etc. It's not possible with <iframe/>.
• Figma live embed kit suggests using <iframe/> however also works with <embed/>