Thomas Allmer, founder of Open Web Components (@OpenWc), released MDJS, a Markdown variant that allows developers to include runnable JavaScript code into their Markdown documents. MDJS can be interpreted as regular Markdown content or be progressively enhanced to produce interactive documentation including web components.
MDJS enhances Markdown’s fenced code blocks syntax with three new constructs: script, story, preview-story.
The following markdown source:
```js script
import './my-component.js';
```
# This is my component
<my-component></my-component>
will generate the following JavaScript and HTML code:
import './my-component.js';
<h1>This is my component</h1>
<my-component></my-component>
The script annotation to the js code block thus allows developers to load web components and use it in a markdown source.
The second annotation <story> can be used as follows:
```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>
`;
```
The previous embedded JavaScript includes a factory function which uses lit-html templating to produce HTML. The previous code will lead to the generation of the following JavaScript and 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>
The <mdjs-story/> web component is provided by MDJS and wraps the user-provided web component. The preview-story adds a similar functionality to that of story, albeit with a border around the component and a button to show/hide the actual source code.
MDJS reads like standard markdown, meaning it can be used verbatim outside MDJS contexts and use cases. The fence code blocks will then be displayed as code, as expected. MDJS, however, enhances the standard markdown behavior with extra interactivity provided by the loaded web component, and the source code preview functionality. MDJS thus allows developers to create interactive demos with Markdown, JavaScript and web components. This, for instance, addresses the use cases of developers seeking to document design systems based on web components.
As of today, MDJS can be used either locally via es-dev-server, or via Storybook, or in GitHub pages (for instance README page, or issue page), or in the webcomponents.dev IDE.
Allmer summarizes MDJS use cases as follows:
There you have it - MDJS is a format that can be shown in many different ways.
It is your single source of truth for good looking documentation everywhere.
Be it locally, a published Storybook, on GitHub or npmjs it always looks good even if there is no direct support for it, but when possible it will become interactive demos through progressive enhancement.
MDJS offers functionality similar to MDX which includes JSX in Markdown. While JSX was developed to interact with the React ecosystem in mind, MDJS relies on standard JavaScript and web components as implemented in most browsers. Additionally, MDJS source can be used anywhere Markdown can be used.
MDJS roadmap includes improving styling, supporting other renderers than lit-html, the highlighting of code snippets, and more. Developers may review the official documentation page at https://open-wc.org/mdjs/.
