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