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

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

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

以下 Markdown 源代码：

​```js script
import './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，高亮显示代码段，等等。开发人员可以点击这里查看官方文档。

作者：Bruno Couriol

译者：平川

来源：InfoQ