@d4kmor/mdjs-core v0.0.5
Markdown JavaScript Format
Part of Open Web Components
Open Web Components provides a set of defaults, recommendations and tools to help facilitate your web component project. Our recommendations include: developing, linting, testing, building, tooling, demoing, publishing and automating.
Format
The format is meant to allow using JavaScript with Markdown. It does so by "annotating" JavaScript that should be execute in Markdown.
All you need to do is have 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-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 like
js story
The code snippet will actually get executed at that place and you will have a live demo
```js story
export const JsStory = () =>
html`
<demo-wc-card>JS Story</demo-wc-card>
`;
```full code support
```js story
export const JsStory = () => {
const calculateSomething = 12;
return html`
<demo-wc-card .header=${`Something: ${calculateSomething}`}>JS Story</demo-wc-card>
`;
};
```js preview story
Will become a live demo wrapped in a container with a show code button.
```js preview-story
export const JsStory = () =>
html`
<demo-wc-card>JS Story</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('@open-wc/mdjs'); module.exports = { nodeResolve: true, open: 'README.md', watch: true, responseTransformers: [mdjsTransformer], };
Storybook
Please check out storybook-addon-markdown-docs.
Chrome Extension for Github (early Prove of Concept)
See live demos directly your 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('@open-wc/mdjs');
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('@open-wc/mdjs');
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('@open-wc/mdjs');
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 {
// ...