Markdown JavaScript: 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 script.
```js script
// 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
<my-card>
<h2>Hello world!</h2>
<button>Click me!</button>
</my-card>
```
You can even execute some JavaScript:
## This is my-el
<my-el></my-el>
```js script
import { LitElement, html } from 'https://unpkg.com/lit-element?module';
class MyEl extends LitElement {
render() {
this.innerHTML = '<p style="color: red">I am alive</p>';
}
}
customElements.define('my-el', MyEl);
```
Demo Support (Story)
mdjs comes with some additional helpers you can choose to import via
```js script
import '@mdjs/mdjs-story/mdjs-story.js';
import '@mdjs/mdjs-preview/mdjs-preview.js';
```
once loaded you can use them like so.
```js script
import '@mdjs/mdjs-story/mdjs-story.js';
import '@mdjs/mdjs-preview/mdjs-preview.js';
```
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
<demo-wc-card>HTML Story</demo-wc-card>
```
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
<demo-wc-card>HTML Preview Story</demo-wc-card>
```
Here is a live example from demo-wc-card.
Supported Systems
es-dev-server
Preview your mdjs readme with live demos and auto reload.
-
Add to your
package.json:"scripts": { "start": "es-dev-server", } -
Create a
es-dev-server.config.jsin the root of your repo.const { mdjsTransformer } = require('@mdjs/core'); module.exports = { nodeResolve: true, open: 'README.md', watch: true, responseTransformers: [mdjsTransformer], };
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 page, 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 jsCode 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 {
// ...