@aegisjsproject/md-editor
Version:
A custom Markdown editor component with preview as a form input element
113 lines (84 loc) • 5.37 kB
Markdown
# `@aegisjsproject/md-editor`
A custom Markdown editor component with preview as a form input element
[](https://github.com/AegisJSProject/md-editor/actions/workflows/codeql-analysis.yml)
[](https://github.com/AegisJSProject/md-editor/blob/master/LICENSE)
[](https://github.com/AegisJSProject/md-editor/commits/master)
[](https://github.com/AegisJSProject/md-editor/releases)
[](https://github.com/sponsors/shgysk8zer0)
[](https://www.npmjs.com/package/@aegisjsproject/md-editor)
[](https://www.npmjs.com/package/@aegisjsproject/md-editor)
[](https://github.com/AegisJSProject)
[](https://twitter.com/shgysk8zer0)
[](https://liberapay.com/shgysk8zer0/donate "Donate using Liberapay")
- - -
- [Code of Conduct](./.github/CODE_OF_CONDUCT.md)
- [Contributing](./.github/CONTRIBUTING.md)
<!-- - [Security Policy](./.github/SECURITY.md) -->
## Installation
### Node Instructions
```bash
npm i @aegisjsproject/md-editor
```
### Using [`<script type="importmap">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) and a CDN
```html
<script type="importmap">
{
"imports": {
"@aegisjsproject/md-editor": "https://unpkg.com/@aegisjsproject/md-editor@1.0.0/md-editor.min.js"
}
}
</script>
```
### Just Using a `<script>`
```html
<script src="https://unpkg.com/@aegisjsproject/md-editor@1.0.0/md-editor.min.js" crossorigin="anonymous" referrerpolicy="no-referrer" defer=""></script>
```
## Example Usage
### Just using HTML
```html
<form id="post">
<label for="content">Content</label>
<!-- This behaves basically like a textarea or any input -->
<md-editor name="content" id="content" minlength="40" mode="editor" required="">
# Hello, World!
</md-editor>
<!-- Rest of form stuff -->
</form>
```
### Creating through Scripting
```js
// Need to import if not already added
import '@aegisjsproject/md-editor';
// Get the component class
const HTMLMarkdownEditorElement = customElements.get('md-editor');
// Create and setup the element
const editor = new HTMLMarkdownEditorElement();
editor.name = 'content';
editor.id = 'content';
// Optionally bind to `history.state[whatever]
editor.textContent = history.state?.content;
editor.addEventListener('change', ({ target }) => history.replaceState({ content: target.value }, '', location.href), { passive: true });
// Add to the form, after its `<label>`
document.querySelector(`label[for="${editor.id}"]`).after(editor);
```
## Usage Notes and Browser APIs
This component utilizes some proposed and experimental APIs including `Element.prototype.setHTML` (this [Sanitizer API](https://github.com/WICG/sanitizer-api))
and [`String.dedent`](https://github.com/tc39/proposal-string-dedent). These APIs **MUST** be polyfilled. You may find
the required polyfills in [`@shgysk8zer0/polyfills`](https://npmjs.com/package/@shgysk8zer0/polyfills) or provide your own.
## Security
Like all `@aegisjsproject` libraries, this component is indended to be safe and compatible in highly secure contexts. It
is designed to work with a very restricted [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy)
as well as [the Trusted Types API](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API).
### Example CSP
Note the [SRI](https://developer.mozilla.org/en-US/docs/Web/Security/Practical_implementation_guides/SRI) Integrity used
for a `<script type="importmap">` and the Trusted Types Policy of `aegis-sanitizer#html` (required for the Sanitizer API polyfill).
```
Content-Security-Policy: default-src 'self'; script-src 'self' https://unpkg.com/@shgysk8zer0/ https://unpkg.com/@aegisjsproject/ 'sha384-XYouuKGvd2BSrapxPZFWENl9b0loR7EVyC2cls6tQ/Oa+3R/uWw6TQ+nWa4/zt9l'; style-src 'self' https://unpkg.com/@highlightjs/ https://unpkg.com/@aegisjsproject/; img-src 'self'; trusted-types aegis-sanitizer#html; require-trusted-types-for 'script';
```