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

原文链接：

New MDJS Markup Language Adds JavaScript to Markdown for Interactive Documentation