New markup language MDJS adds JavaScript to Markdown for interactive documentation

Thomas Allmerfounder of Open Web Components (@OpenWc), released MDJS, a Markdown variant that allows developers to include executable JavaScript code in their Markdown documents. MDJS can be interpreted as normal Markdown content or incrementally enhanced to produce interactive documentation including web components.

MDJS improves Markdown’s closed code block 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 componenth1>
<my-component>my-component>

The script annotation at the js The code block thus allows developers to load web components and use them in a markdown source.

The second annotation 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>  
`;  
```

Link to editable demo.

The previous built-in JavaScript includes a factory function that uses lit-html templates to produce HTML. The preceding code will lead to the generation of the following JavaScript and HTML code:

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

export const demo = () => html`
  
`;
<h1>This is my componenth1>
<mdjs-story mdjs-story-name="demo">
  #shadow-root (open)
  <demo-wc-card>demo-wc-card>
mdjs-story>

Link to editable demo.

the The web component is provided by MDJS and encapsulates the user-provided web component. the preview-story adds functionality similar to story, but 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 of MDJS contexts and use cases. The closing code blocks will then be displayed as code, as expected. MDJS, however, enhances the standard markdown behavior with additional interactivity provided by the loaded web component and source code preview functionality. MDJS thus allows developers to create interactive demos with Markdown, JavaScript and web components. This, for example, is for use cases of developers looking to document web component-based design systems.

As of today, MDJS can be used either locally through es-dev-server, or through Storybook, or in GitHub pages (e.g. README page or issue page), or in the webcomponents.dev IDE.

Allmer summarizes the use cases for MDJS as follows:

That’s it, MDJS is a format that can be displayed in different ways.
It’s your only source of truth for quality documentation anywhere.
Whether locally, a published Storybook, on GitHub or npmjs, it still looks good even if there is no direct support, but where possible it will become interactive demos through incremental improvement .

MDJS offers similar functionality 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, the MDJS source can be used wherever Markdown can be used.

The MDJS roadmap includes styling improvements, support for other renderers than lit-html, snippet highlighting, and more. Developers can check the official documentation page at https://open-wc.org/mdjs/.

Sam D. Gomez