Categories
程式開發

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  

將生成下面的JavaScript和HTML代碼:

import './my-component.js';  

This is 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`  
  
`;  
​```

可編輯演示文檔鏈接

上例中嵌入的JavaScript包含一個工廠函數,使用lit-html模板來生成HTML。以上代碼將生成以下JavaScript和HTML:

import './demo-wc-card.js';
import { html } from 'lit-html';

export const demo = () => html`
  
`;

This is my component

#shadow-root (open)

可編輯演示文檔鏈接

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