Overview
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
<my-el></my-el>
```js client
import { LitElement, html } from 'https://unpkg.com/lit-element?module';
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:
Story
The code snippet will actually get executed at that place and you will have a live demo
```js story
export const JsStory = () => html``;
```
```html story
HTML Story
```
Full Code Support
```js story
export const JsStory = () => {
const calculateSomething = 12;
return html``;
};
```
Preview Story
Will become a live demo wrapped in a container with a show code button.
```js preview-story
export const JsPreviewStory = () => html``;
```
```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``;
```
```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 -->
<Button
android:id="@+id/demoWcCard"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Android Code"
style="@style/Widget.FooComponents.Demo.Wc.Card"
/>
// will be visible when platform ios is selected
import DemoWc.Card
let card = DemoWcButton()
Supported Systems
Storybook
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
Basic
mdjs offers two more "basic" integrations
mdjsDocPage
Creates a full blown HTML page by passing in the Markdown.
const { mdjsDocPage } = require('@mdjs/core');
const page = await mdjsDocPage(markdownString);
/*
<html>
... // load styles/components for mdjs, start stories
<body>
<h1>Some Markdown</h1>
</body>
</html>
*/
mdjsProcess
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);
console.log(data);
/*
{
jsCode: "
import '@mdjs/mdjs-story/mdjs-story.js';
...
",
html: '<h1>Markdown One</h1>',
}
*/
Advanced
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 } = result.data;
console.log(result.contents);
// <h1>This is my-el></h1>
// <my-el></my-el>
console.log(jsCode);
// customElements.define('my-el', class extends HTMLElement {
// ...