https://github.com/hilookas/markdown-it-directive-webcomponents
Convert a markdown directive to a web component.
https://github.com/hilookas/markdown-it-directive-webcomponents
markdown markdown-it markdown-it-plugin react vue webcomponents
Last synced: 2 months ago
JSON representation
Convert a markdown directive to a web component.
- Host: GitHub
- URL: https://github.com/hilookas/markdown-it-directive-webcomponents
- Owner: hilookas
- License: mit
- Created: 2020-05-05T15:02:35.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2022-01-12T23:03:19.000Z (over 4 years ago)
- Last Synced: 2025-08-31T13:02:21.299Z (8 months ago)
- Topics: markdown, markdown-it, markdown-it-plugin, react, vue, webcomponents
- Language: JavaScript
- Homepage:
- Size: 17.6 KB
- Stars: 3
- Watchers: 1
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# markdown-it-directive-webcomponents
[中文指南](README.zh.md)
This plugin can convert a markdown directive ([Generic directives/plugins syntax spec](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444)) to a web component ([WebComponents](https://developer.mozilla.org/en-US/docs/Web/Web_Components)). It needs [markdown-it-directive](https://github.com/hilookas/markdown-it-directive) and [markdown-it](https://github.com/markdown-it/markdown-it) as dependencies.
## Install
`npm i markdown-it-directive-webcomponents`
## API
```javascript
const md = require('markdown-it')()
.use(require('markdown-it-directive-webcomponents'), {
components: [
{
present: 'both',
name: 'directive-name',
tag: 'tag-name',
allowedAttrs: [ 'inline', 'src', 'title', /^prefix/ ],
destLinkName: 'my-link-name',
destStringName: 'my-string-name',
parseInner: true
},
]
});
```
- `components`: Write conversion rules in this array
- `present`: Which type of directive to parse. Values: `inline`, `block`, `both`.
- `name`: The name of the directive
- `tag`: The tag name of the converted component
- `allowedAttrs`: Allowed attribute names. If set as an array, elements in the array can be a String or a RegEx. If not set, allow any name. (has security issues, not recommended)
- `destLinkName`: Attribute name when converting link-type data in link destinations (ie. the content in `()`) to attributes. `src` by default
- `destStringName`: Attribute name when converting string-type data in link destinations to attributes. `title` by default
- `parseInner`: Whether to continue to parse the content as Markdown or not. Bool type. if it is `false`, the content will be unescaped and written in the output (html `< >` etc. will still be escaped).
[DOMPurify](https://github.com/cure53/DOMPurify) is recommended as a security backup.
Here are three directive formats that can be recognized:
```text
text before :directive-name[content](/link "destination" /another "one"){.class #id name=value name="string!"} text after
:: directive-name [inline content] (/link "destination" /another "one") {.class #id name=value name="string!"} content title ::
::: directive-name [inline content] (/link "destination" /another "one") {.class #id name=value name="string!"} content title ::
content
:::
```
Will be converted to:
```html
text before content text after
inline content
content
```
In the conversion process, link-type value which in `()` will add to `src` attribute, and string-type value will add to `title` attribute. `class`'s values will be merged together and other attributes will pick the first value.
Block-level directive, if it is the third case, it will ignore the inline content and content title, and parse the content as block; if the second case, if there is, then use inline content otherwise use content title as content and parse the content as inline.
## Example
```javascript
const md = require('markdown-it')()
.use(require('markdown-it-directive-webcomponents'), {
components: [
{
present: 'both',
name: 'directive-name',
tag: 'tag-name',
allowedAttrs: [ 'inline', 'src', 'title', /^prefix/ ],
parseInner: true
},
{
present: 'both',
name: 'another-directive',
tag: 'another-tag',
allowedAttrs: [ 'inline', 'src', 'title', /^prefix/ ],
parseInner: false
},
]
});
console.dir(md.render(`
text before :directive-name[content](/link "destination" /another "one"){.class #id name=value name="string!"} text after
:: directive-name [inline content] (/link "destination" /another "one") {.class #id name=value name="string!"} content title ::
::: directive-name [inline content] (/link "destination" /another "one") {.class #id name=value name="string!"} content title ::
content
:::
::: another-directive
content
\\:::
:::`));
/* output
text before content text after
inline content
content
content
:::
*/
```
More examples can be found in `test.js`.
## License
[MIT](http://opensource.org/licenses/MIT)
Copyright (c) 2020, lookas