MDJS:可将 JavaScript 添加到 Markdown,创建交互式文档

发布于 2020-9-8 09:54
浏览
0收藏

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

收藏
回复
举报
回复
添加资源
添加资源将有机会获得更多曝光,你也可以直接关联已上传资源 去关联
    相关推荐