MDJS：可将 JavaScript 添加到 Markdown，创建交互式文档

Open Web Components（@OpenWc）创建者Thomas Allmer发布了MDJS，这是一种 Markdown 变体，支持在 Markdown 文档中包含可运行的 JavaScript 代码。MDJS 可以解释为常规的 Markdown 内容，也可以进一步升级为带有 Web 组件的交互式文档。

MDJS 通过三个新结构增强了 Markdown 的代码块语法：script、story、preview-story。

以下 Markdown 源代码：

​```js scriptimport './my-component.js';  ​```
# This is my component  <my-component></my-component>

将生成下面的 JavaScript 和 HTML 代码：

import './my-component.js';  
<h1>This is my component</h1><my-component></my-component>

js代码块的script注解用来加载 Web 组件并在 Markdown 源代码中使用。

第二个注解 story 用法如下：

​```js script  import './demo-wc-card.js';  import { html } from 'lit-html';  ​```  
# This is my component  
​```js story  export const demo = () => html`  <demo-wc-card header="HEADER"></demo-wc-card>  `;  ​```

可编辑演示文档链接

上例中嵌入的 JavaScript 包含一个工厂函数，使用 lit-html 模板来生成 HTML。以上代码将生成以下 JavaScript 和 HTML：

import './demo-wc-card.js';import { html } from 'lit-html';
export const demo = () => html`  <demo-wc-card></demo-wc-card>`;
<h1>This is my component</h1><mdjs-story mdjs-story-name="demo">  #shadow-root (open)  <demo-wc-card></demo-wc-card></mdjs-story>

可编辑演示文档链接

Web 组件是由 MDJS 提供的，它封装了用户提供的 Web 组件。preview-story 添加了与 story 类似的功能，不过组件会有边框，还会有一个按钮，用来显示/隐藏实际的源代码。

MDJS 读起来像标准的 Markdown，不需要修改就可以在 MDJS 上下文或场景之外使用。代码块将正常显示代码。不过，MDJS 增强了标准的 Markdown 行为（通过加载的 Web 组件所提供的额外交互性）和源代码预览功能。这样，开发人员就可以使用 Markdown、JavaScript 和 Web 组件创建交互式演示文档。举例来说，开发人员可以用它记录基于 Web 组件的系统设计过程。

到目前为止，MDJS 既可以通过 es-dev-server 在本地使用，也可以通过 Storybook 使用，还可以在 GitHub 页面（例如 README 页面或问题页面）或在webcomponents.dev IDE 中使用。

Allmer 将 MDJS 的用例总结如下：

MDJS 是一种可以以多种不同的方式显示的格式。

让漂亮的文档随处可见。

在本地、已发布的 Storybook、GitHub 或 npmjs 上，即使没有直接的支持，也没有问题，只要可能，它就可升级为交互式演示文档。

MDJS 提供了与 MDX 类似的功能，后者在 Markdown 中包含了JSX。JSX 是为了与 React 生态系统进行交互而开发的，而 MDJS 依赖于已在大多数浏览器中实现的标准 JavaScript 和 Web 组件。此外，MDJS 源代码可以在任何地方使用。

MDJS 的路线图包括改进样式，支持更多的渲染器，而不仅仅是 litt -html，高亮显示代码段，等等。开发人员可以点击这里查看官方文档。

原文链接：

New MDJS Markup Language Adds JavaScript to Markdown for Interactive Documentation