Open Web Components（@OpenWc）の創設者であるThomas Allmer氏はMDJSをリリースした。MDJSは、Markdownの一種であり、開発者が自身のMarkdownドキュメントに実行可能なJavaScriptコードを含めることができる。MDJSは、通常のMarkdownコンテンツとして解釈することも、Webコンポーネントを含むインタラクティブなドキュメントを生成するために徐々に拡張することもできる。
MDJSは、Markdownのフェンスコードブロック構文を、script、story、preview-storyという3つの新しい構成で拡張する。
次のマークダウンソースから、
```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コードブロックへのスクリプトアノテーションにより、開発者はWebコンポーネントをロードして、マークダウンソース内で使用できる。
2番目のアノテーション<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>
<mdjs-story/>WebコンポーネントはMDJSによって提供され、ユーザが提供するWebコンポーネントをラップする。preview-storyは、コンポーネントの境界線と実際のソースコードを表示/非表示にするボタンに加え、同様の機能をstoryの機能に追加する。
MDJSは標準のマークダウンのように読み取る。つまり、MDJSコンテキストとユースケースの外部でそのまま使用できる。期待どおり、フェンスコードブロックがコードとして表示される。ただし、MDJSは、ロードされたWebコンポーネントとソースコードプレビュー機能によって提供される追加の対話機能により、標準のマークダウン動作を強化する。MDJSを使用すると、開発者はMarkdown、JavaScript、Webコンポーネントを使用してインタラクティブなデモを作成できる。これは、たとえば、Webコンポーネントに基づいて設計システムを文書化しようとする開発者のユースケースに対応できる。
現在のところ、MDJSはes-dev-serverを介してローカルで、あるいはStorybookを介して、あるいはGitHubページ（たとえば、READMEページ、イシューページ）、あるいはwebcomponents.dev IDEで使用できる。
Allmer氏はMDJSの使用例を次のように要約している。
ここであなたに提供されるMDJSは、さまざまな方法で表示できるフォーマットのことです。
あらゆる場所で見栄えのよいドキュメントを作成するための信頼できる唯一の情報源です。
ローカル、公開されたストーリーブック、GitHub、npmjsのいずれにおいても、たとえ、それらが直接サポートされていなくても、常に見栄えがよいです。ただし、段階的な拡張によりインタラクティブなデモになることもある。
MDJSは、Markdown内にJSXを含むMDXと類似の機能を提供する。JSXはReactエコシステムと対話するために開発されたが、MDJSはほとんどのブラウザに実装されている標準のJavaScriptおよびWebコンポーネントに依存している。さらに、MDJSソースは、Markdownを使用できる場所であればどこでも使用できる。
MDJSロードマップには、スタイルの改善、lit-html以外のレンダラーのサポート、コードスニペットの強調表示などが含まれる。開発者は、https://open-wc.org/mdjs/の公式ドキュメントページを確認できる。