Rocket Logo Rocket Docs Themes Tools Blog
Rocket Logo Rocket


Markdown JavaScript (mdjs) is a format that allows you to use JavaScript with Markdown, to create interactive demos. It does so by "annotating" JavaScript that should be executed in Markdown.

To annotate we use a code block with js client.

```js client
// execute me

Web Components

One very good use case for that can be web components. HTML already works in Markdown so all you need is to load a web components definition file.

You could even do so within the same Markdown file.

## This is my-card

Here's an example of the component:

```html preview-story

  Hello world!
  Click me!


You can even execute some JavaScript:

## This is my-el


```js client
import { LitElement, html } from '';

class MyEl extends LitElement {
  render() {
    this.innerHTML = 'I am alive';

customElements.define('my-el', MyEl);

Demo Support (Story)

mdjs comes with some additional helpers you can choose to import:

```js client
import '@mdjs/mdjs-story/define';
import '@mdjs/mdjs-preview/define';

Once loaded you can use them like so:


The code snippet will actually get executed at that place and you will have a live demo

```js story
export const JsStory = () => html` JS Story `;
```html story
HTML Story

Full Code Support

```js story
export const JsStory = () => {
  const calculateSomething = 12;
  return html`
    JS Story

Preview Story

Will become a live demo wrapped in a container with a show code button.

```js preview-story
export const JsPreviewStory = () => html` JS Preview Story `;
```html preview-story
HTML Preview Story

Here is a live example from demo-wc-card.

import 'demo-wc-card/demo-wc-card.js';
export const header = () => {
  return html` <demo-wc-card .header=${'my new header'}></demo-wc-card> `;
// not defined for android
// not defined for ios

Story Code

If your preview is followed by a code blocks marked as story-code then those will be shown when switching between multiple platforms

```js preview-story
// will be visible when platform web is selected
export const JsPreviewStory = () => html` JS Preview Story `;

```xml story-code


```swift story-code
// will be visible when platform ios is selected
import DemoWc.Card

let card = DemoWcButton()

See it in action by opening up the code block and switching platforms

// will be visible when platform web is selected
export const JsPreviewStory = () => html` <demo-wc-card>JS Preview Story</demo-wc-card> `;
<!-- will be visible when platform android is selected -->
    android:text="Android Code"
// will be visible when platform ios is selected
import DemoWc.Card

let card = DemoWcButton()

Supported Systems


Please check out @open-wc/demoing-storybook for a fully integrated setup.

It includes storybook-addon-markdown-docs which uses mdjs under the hood.

Chrome Extension (currently only for GitHub)

See live demos directly inside GitHub pages, Markdown files, issues, pull requests...

Please check out mdjs-viewer.

Build mdjs


mdjs offers two more "basic" integrations


Creates a full blown HTML page by passing in the Markdown.

const { mdjsDocPage } = require('@mdjs/core');

const page = await mdjsDocPage(markdownString);
  ... // load styles/components for mdjs, start stories
    <h1>Some Markdown</h1>


Pass in multiple Markdown documents and you get back all the JavaScript code and rendered HTML.

const { mdjsProcess } = require('@mdjs/core');

const data = await mdjsProcess(markdownString);
  jsCode: "
    import '@mdjs/mdjs-story/mdjs-story.js';
  html: '<h1>Markdown One</h1>',


mdjs is build to be integrated within the unifiedjs system.

const unified = require('unified');
const markdown = require('remark-parse');
const htmlStringify = require('remark-html');
const mdjsParse = require('@mdjs/core');

const parser = unified().use(markdown).use(mdjsParse).use(htmlStringify);
const result = await parser.process(body);
const { jsCode } =;
// <h1>This is my-el></h1>
// <my-el></my-el>
// customElements.define('my-el', class extends HTMLElement {
// ...