wc-markdown-loader

Web Component Markdown Loader

Webpack loader that parses markdown files and converts them to Web Components. It will also parse FrontMatter to import dependencies and render components. Provides support for syntax highlighting via prismjs

This loader is a modified fork from javiercf/react-markdown-loader and can easily be used in conjunction with Create-Evergreen-App and Greenwood. It's still in the early stages and contributions are welcome.

Install

npm i --save-dev wc-markdown-loader

Usage

In the FrontMatter you should import the components you want to render with the component name as a key and it's path as the value. Use the label key to indicate the unique name you want to register the markdown files as which you can then load in your app as <wc-md-hello /> for example.

---
label: 'hello'
imports:
  Button: './button.js'
  HelloWorld: './hello-world.js'

webpack.config.js

module: {
  loaders: [
    {
      test: /\.md$/,
      loader: 'wc-markdown-loader'
    }
  ]
}

hello-world.js

import { html, LitElement } from 'lit-element';

class HelloWorld extends LitElement {

  static get properties() {
    return {
      label: String
    };
  }
  render() {
    return html `<div>Hello ${this.label}</div>`;
  }
}

customElements.define('hello-world', HelloWorld);

hello-world.md

---
label: 'hello'
imports:
  HelloWorld: './hello-world.js'
---
# Hello World

This is an example component rendered from markdown

<hello-world label="world"></hello-world>

This is an example code block rendered with syntax highlighter

```html
<hello-world label="world"></hello-world>
```

app.js

The component you want to render your new markdown webcomponent

import { html, LitElement } from 'lit-element';
import './hello-world.md';

class AppComponent extends LitElement {

  render() {
    return html`
      <wc-md-hello></wc-md-hello>
    `;
  }
}

customElements.define('eve-app', AppComponent);

Advanced Options

LightDOM

If you want to disable shadowRoot and instead have your markdown component render in the root node, you can add the following to your webpack config.

webpack.config.js

module: {
  rules: [
    {
      test: /\.md$/,
      loader: 'wc-markdown-loader',
      options: {
        shadowRoot: false
      }
    }
  ]
}

This is if you need to manipulate this component from a parent component etc.

Custom Style

If you want to set a global custom style to use for your markdown components, you can do so from your webpack config. Keep in mind that this is relative to the working directory. You may need to use a path.join(__dirname, 'mypath/mypath.css'). The example below demonstrates a prismjs theme from node_modules/prismjs/themes/prism-tomorrow.css.

webpack.config.js

module: {
  rules: [
    {
      test: /\.md$/,
      loader: 'wc-markdown-loader',
      options: {
        defaultStyle: false,
        customStyle: 'prismjs/themes/prism-tomorrow.css'
      }
    }
  ]
}

note: You can toggle the defaultStyle as well, it will have a lower specificity than the customStyle.

Unified Presets

You can utilize unified presets via the preset option within the loader. The presets are placed in the unified process array after remark is converted to rehype.

webpack.config.js

module: {
  rules: [
    {
      test: /\.md$/,
      loader: 'wc-markdown-loader',
      options: {
        preset: {
          settings: {bullet: '*', emphasis: '*', fences: true},
            plugins: [
              require('rehype-slug'),
              require('rehype-autolink-headings')
            ]
          ]
        }
      }
    }
  ]
}

Graph

If you want to pre-scaffold an application with a graph of all md files paths and add your own generated labels(removing the need to cite label in each of the file's front-matter), you can create a graph array, write the serialized json to a cache file, then add the path of that .json file to the options of the loader e.g.

graph.json file:

[
  {
    "filePath": "/home/user/workspace/app/src/pages/mypage.md"
    "label": "some-generated-label-asjhfkawa"
  },
  {
    "filePath": "/home/user/workspace/app/src/pages/myotherpage.md"
    "label": "some-generated-label-jkhkdsfskwad"
  }
]

webpack.config.js

module: {
  rules: [
    {
      test: /\.md$/,
      loader: 'wc-markdown-loader',
      options: {
        graph: path.join(__dirname, 'graph.json')
      }
    }
  ]
}

Note: this is overridden if a .md file contains the label variable, at the top, in front-matter.

Markdown pages that do not contain a label front-matter variable, and without any graph added to loader options, will be defined using the last 15 characters of a sha256 hash of the file's resource path, as well as prepended with wc-md-. e.g. <wc-md-4e53214c7f8108e></wc-md-4e53214c7f8108e>.

All compiled md component labels are automatically prefixed with wc-md- for example: <wc-md-hello-world></wc-md-hello-world>

This advanced usage is useful for example if you need to know the element name for a lit-redux-route and don't want to pre-label every single md file.

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

License

MIT (c) 2019