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

  • 发表于:
  • 本文为 InfoQ 中文站特供稿件
  • 首发地址https://www.infoq.cn/article/Sg57pfyuQUGefy7iYVDD
  • 如有侵权,请联系 yunjia_community@tencent.com 删除。

扫码关注云+社区

领取腾讯云代金券