@d4kmor/mdjs-core

v0.0.5

Published

3 years ago

Combine Markdown with JavaScript

Downloads

0High
0Medium
0Low

d4kmor

open-wc markdown unified remark

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.js in 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 {
// ...