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，高亮顯示代碼段，等等。開發人員可以點選這裡檢視官方文檔。

【雲栖号線上課堂】每天都有産品技術專家分享！

課程位址：

https://yqh.aliyun.com/zhibo

立即加入社群，與專家面對面，及時了解課程最新動态！

【雲栖号線上課堂 社群】

https://c.tb.cn/F3.Z8gvnK

原文釋出時間：2020-04-27

本文作者：Bruno Couriol

本文來自：“

InfoQ

”，了解相關資訊可以關注“

”