Socket
Socket
Sign inDemoInstall

remark-html

Package Overview
Dependencies
Maintainers
2
Versions
32
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

remark-html - npm Package Compare versions

Comparing version 13.0.2 to 15.0.2

index.d.ts

78

index.js

@@ -1,16 +0,33 @@

'use strict'
/**
* @typedef {import('mdast').Root} Root
* @typedef {import('hast-util-sanitize').Schema} Schema
*
* @typedef ExtraOptionsFields
* Configuration (optional).
* @property {boolean|Schema|null} [sanitize]
* How to sanitize the output.
* @property {import('mdast-util-to-hast').Handlers} [handlers={}]
* Object mapping mdast nodes to functions handling them.
*
* @typedef {import('hast-util-to-html').Options & ExtraOptionsFields} Options
*/
var toHast = require('mdast-util-to-hast')
var toHtml = require('hast-util-to-html')
var sanitize = require('hast-util-sanitize')
import {toHtml} from 'hast-util-to-html'
import {sanitize} from 'hast-util-sanitize'
import {toHast} from 'mdast-util-to-hast'
module.exports = plugin
function plugin(options) {
var settings = Object.assign({}, options || {})
/**
* Plugin to serialize markdown as HTML.
*
* @this {import('unified').Processor}
* @type {import('unified').Plugin<[Options?] | [], Root, string>}
*/
export default function remarkHtml(settings = {}) {
const options = {...settings}
/** @type {boolean|undefined} */
let clean
if (typeof settings.sanitize === 'boolean') {
clean = settings.sanitize
settings.sanitize = undefined
if (typeof options.sanitize === 'boolean') {
clean = options.sanitize
options.sanitize = undefined
}

@@ -22,11 +39,19 @@

this.Compiler = compiler
Object.assign(this, {Compiler: compiler})
/**
* @type {import('unified').CompilerFunction<Root, string>}
*/
function compiler(node, file) {
var root = node && node.type && node.type === 'root'
var hast = toHast(node, {
const hast = toHast(node, {
allowDangerousHtml: !clean,
handlers: settings.handlers
handlers: options.handlers
})
var result
// @ts-expect-error: assume root.
const cleanHast = clean ? sanitize(hast, options.sanitize) : hast
const result = toHtml(
// @ts-expect-error: assume root.
cleanHast,
Object.assign({}, options, {allowDangerousHtml: !clean})
)

@@ -37,18 +62,11 @@ if (file.extname) {

if (clean) {
hast = sanitize(hast, settings.sanitize)
}
result = toHtml(
hast,
Object.assign({}, settings, {allowDangerousHtml: !clean})
)
// Add an eof eol.
if (root && result && /[^\r\n]/.test(result.charAt(result.length - 1))) {
result += '\n'
}
return result
return node &&
node.type &&
node.type === 'root' &&
result &&
/[^\r\n]/.test(result.charAt(result.length - 1))
? result + '\n'
: result
}
}

90

package.json
{
"name": "remark-html",
"version": "13.0.2",
"version": "15.0.2",
"description": "remark plugin to compile Markdown to HTML",

@@ -31,50 +31,47 @@ "license": "MIT",

],
"types": "types/index.d.ts",
"sideEffects": false,
"type": "module",
"main": "index.js",
"types": "index.d.ts",
"files": [
"types/index.d.ts",
"index.d.ts",
"index.js"
],
"dependencies": {
"hast-util-sanitize": "^3.0.0",
"hast-util-to-html": "^7.0.0",
"mdast-util-to-hast": "^10.0.0"
"@types/mdast": "^3.0.0",
"hast-util-sanitize": "^4.0.0",
"hast-util-to-html": "^8.0.0",
"mdast-util-to-hast": "^12.0.0",
"unified": "^10.0.0"
},
"devDependencies": {
"browserify": "^16.0.0",
"commonmark.json": "^0.29.0",
"dtslint": "^4.0.0",
"is-hidden": "^1.0.0",
"not": "^0.1.0",
"nyc": "^15.0.0",
"@types/tape": "^4.0.0",
"c8": "^7.0.0",
"commonmark.json": "^0.30.0",
"is-hidden": "^2.0.0",
"prettier": "^2.0.0",
"rehype-parse": "^7.0.0",
"rehype-stringify": "^8.0.0",
"remark": "^13.0.0-alpha.0",
"remark-cli": "^8.0.0",
"remark-github": "^9.0.0",
"remark-preset-wooorm": "^7.0.0",
"remark-slug": "^6.0.0",
"remark-toc": "^7.0.0",
"rehype-parse": "^8.0.0",
"rehype-stringify": "^9.0.0",
"remark": "^14.0.0",
"remark-cli": "^10.0.0",
"remark-frontmatter": "^4.0.0",
"remark-gfm": "^3.0.0",
"remark-github": "^11.0.0",
"remark-preset-wooorm": "^9.0.0",
"remark-slug": "^7.0.0",
"remark-toc": "^8.0.0",
"rimraf": "^3.0.0",
"tape": "^5.0.0",
"tinyify": "^3.0.0",
"to-vfile": "^6.0.0",
"unified": "^9.0.0",
"xo": "^0.33.0"
"to-vfile": "^7.0.0",
"type-coverage": "^2.0.0",
"typescript": "^4.0.0",
"xo": "^0.47.0"
},
"scripts": {
"format": "remark . -qfo --ignore-pattern test/ && prettier . --write && xo --fix",
"build-bundle": "browserify . -s remarkHtml > remark-html.js",
"build-mangle": "browserify . -s remarkHtml -p tinyify > remark-html.min.js",
"build": "npm run build-bundle && npm run build-mangle",
"test-api": "node test",
"test-coverage": "nyc --reporter lcov tape test/index.js",
"test-types": "dtslint types",
"test": "npm run format && npm run build && npm run test-coverage && npm run test-types"
"build": "rimraf \"test/**/*.d.ts\" \"*.d.ts\" && tsc && type-coverage",
"format": "remark . -qfo --ignore-pattern test/ && prettier . -w --loglevel warn && xo --fix",
"test-api": "node --conditions development test/index.js",
"test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov npm run test-api",
"test": "npm run build && npm run format && npm run test-coverage"
},
"nyc": {
"check-coverage": true,
"lines": 100,
"functions": 100,
"branches": 100
},
"prettier": {

@@ -89,12 +86,3 @@ "tabWidth": 2,

"xo": {
"prettier": true,
"esnext": false,
"rules": {
"unicorn/no-fn-reference-in-iterator": "off",
"unicorn/prefer-includes": "off",
"unicorn/prefer-optional-catch-binding": "off"
},
"ignores": [
"remark-html.js"
]
"prettier": true
},

@@ -105,3 +93,9 @@ "remarkConfig": {

]
},
"typeCoverage": {
"atLeast": 100,
"detail": true,
"strict": true,
"ignoreCatch": true
}
}

277

readme.md

@@ -11,20 +11,67 @@ # remark-html

[**remark**][remark] plugin to serialize Markdown as HTML.
**[remark][]** plugin to add support for serializing HTML.
> ⚠️ This package essentially packs [`remark-rehype`][remark2rehype] and
> [`rehype-stringify`][rehype-stringify], and although it does support some
> customisation, it isn’t very pluggable.
> It’s probably smarter to use `remark-rehype` directly and benefit from the
> [**rehype**][rehype] ecosystem.
## Contents
## Note!
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`unified().use(remarkHtml[, options])`](#unifieduseremarkhtml-options)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)
This plugin is ready for the new parser in remark
([`remarkjs/remark#536`](https://github.com/remarkjs/remark/pull/536)).
The current and previous version of the plugin works with the current and
previous version of remark.
## What is this?
This package is a [unified][] ([remark][]) plugin that compiles markdown to
HTML.
**unified** is a project that transforms content with abstract syntax trees
(ASTs).
**remark** adds support for markdown to unified.
**rehype** adds support for HTML to unified.
**mdast** is the markdown AST that remark uses.
**hast** is the HTML AST that rehype uses.
This is a remark plugin that adds a compiler to compile mdast to hast and then
to a string.
## When should I use this?
This plugin is useful when you want to turn markdown into HTML.
It’s a shortcut for `.use(remarkRehype).use(rehypeStringify)`.
The reason that there are different ecosystems for markdown and HTML is that
turning markdown into HTML is, while frequently needed, not the only purpose of
markdown.
Checking (linting) and formatting markdown are also common use cases for
remark and markdown.
There are several aspects of markdown that do not translate 1-to-1 to HTML.
In some cases markdown contains more information than HTML: for example, there
are several ways to add a link in markdown (as in, autolinks: `<https://url>`,
resource links: `[label](url)`, and reference links with definitions:
`[label][id]` and `[id]: url`).
In other cases HTML contains more information than markdown: there are many
tags, which add new meaning (semantics), available in HTML that aren’t available
in markdown.
If there was just one AST, it would be quite hard to perform the tasks that
several remark and rehype plugins currently do.
This plugin is useful when you want to quickly turn markdown into HTML.
In most cases though, it’s recommended to use [`remark-rehype`][remark-rehype]
instead and finally use [`rehype-stringify`][rehype-stringify] to serialize
HTML.
The reason using both ecosystems instead of this plugin is recommended, is that
there are many useful rehype plugins that you can then use.
For example, you can [minify HTML][rehype-minify], [format HTML][rehype-format],
[highlight code][rehype-highlight], [add metadata][rehype-meta], and a lot more.
## Install
[npm][]:
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:

@@ -35,5 +82,19 @@ ```sh

In Deno with [`esm.sh`][esmsh]:
```js
import remarkHtml from 'https://esm.sh/remark-html@15'
```
In browsers with [`esm.sh`][esmsh]:
```html
<script type="module">
import remarkHtml from 'https://esm.sh/remark-html@15?bundle'
</script>
```
## Use
Say we have the following file, `example.md`:
Say we have the following file `example.md`:

@@ -48,20 +109,23 @@ ```markdown

And our script, `example.js`, looks as follows:
And our module `example.js` looks as follows:
```js
var fs = require('fs')
var unified = require('unified')
var markdown = require('remark-parse')
var html = require('remark-html')
import {read} from 'to-vfile'
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkHtml from 'remark-html'
unified()
.use(markdown)
.use(html)
.process(fs.readFileSync('example.md'), function (err, file) {
if (err) throw err
console.log(String(file))
})
main()
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkHtml)
.process(await read('example.md'))
console.log(String(file))
}
```
Now, running `node example` yields:
Now running `node example.js` yields:

@@ -80,15 +144,20 @@ ```html

### `remark().use(html[, options])`
This package exports no identifiers.
The default export is `remarkHtml`.
Serialize Markdown as HTML.
### `unified().use(remarkHtml[, options])`
Add support for serializing HTML.
##### `options`
All options except for `sanitize` and `handlers` are passed to
[`hast-util-to-html`][to-html].
Configuration (optional).
All options other than `sanitize` and `handlers` are passed to
[`hast-util-to-html`][hast-util-to-html].
###### `options.handlers`
Object mapping [mdast][] [nodes][mdast-node] to functions handling them.
This option is passed to [`mdast-util-to-hast`][to-hast-handlers].
This option is a bit advanced as it requires knowledge of ASTs, so we defer
to the documentation available in
[`mdast-util-to-hast`][mdast-util-to-hast].

@@ -100,91 +169,39 @@ ###### `options.sanitize`

* `false`
— HTML is not sanitized, dangerous HTML persists
— output is not sanitized, dangerous raw HTML persists
* `true`
— HTML is sanitized according to [GitHub’s sanitation rules][github],
dangerous HTML is dropped
— output is sanitized according to [GitHub’s sanitation rules][github],
dangerous raw HTML is dropped
* `Object`
— the object is treated as a `schema` for how to sanitize with
[`hast-util-sanitize`][sanitize], dangerous HTML is dropped
— `schema` that defines how to sanitize output with
[`hast-util-sanitize`][sanitize], dangerous raw HTML is dropped
> Note that raw HTML in Markdown cannot be sanitized, so it’s removed.
> A schema can still be used to allow certain values from [integrations][]
> though.
> To support HTML in Markdown, use [`rehype-raw`][raw].
## Types
For example, to add strict sanitation but allowing `className`s, use something
like:
This package is fully typed with [TypeScript][].
It exports an `Options` type, which specifies the interface of the accepted
options.
```js
// ...
var merge = require('deepmerge')
var github = require('hast-util-sanitize/lib/github')
## Compatibility
var schema = merge(github, {attributes: {'*': ['className']}})
Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
Our projects sometimes work with older versions, but this is not guaranteed.
remark()
.use(html, {sanitize: schema})
.processSync(/* … */)
```
This plugin works with `unified` version 6+ and `remark` version 7+.
## Integrations
## Security
`remark-html` works great with:
Use of `remark-html` is **unsafe** by default and opens you up to
[cross-site scripting (XSS)][xss] attacks.
Pass `sanitize: true` to prevent attacks.
Setting `sanitize` to anything else can be unsafe.
* [`remark-autolink-headings`](https://github.com/ben-eb/remark-autolink-headings)
— Automatically add links to headings in Markdown
* [`remark-github`](https://github.com/remarkjs/remark-github)
— Generate references to GitHub issues, PRs, users, and more
* [`remark-highlight.js`](https://github.com/ben-eb/remark-highlight.js)
— Highlight code blocks
* [`remark-html-emoji-image`](https://github.com/jackycute/remark-html-emoji-image)
— Transform emoji unicodes into html images
* [`remark-html-katex`](https://github.com/remark/remark-math/blob/HEAD/packages/remark-html-katex/readme.md)
— Transform math to HTML with KaTeX
* [`remark-math`](https://github.com/rokt33r/remark-math)
— Math support for Markdown (inline and block)
* [`remark-midas`](https://github.com/ben-eb/remark-midas)
— Highlight CSS code with [midas](https://github.com/ben-eb/midas)
* [`remark-toc`](https://github.com/remarkjs/remark-toc)
— Generate a Tables of Contents
* …and [more][remark-plugins]
## Related
All [**mdast** nodes][mdast] can be compiled to HTML.
Unknown **mdast** nodes are compiled to `div` nodes if they have `children` or
`text` nodes if they have `value`.
* [`remark-rehype`](https://github.com/remarkjs/remark-rehype)
— turn markdown into HTML to support rehype
* [`rehype-sanitize`](https://github.com/rehypejs/rehype-sanitize)
— sanitize HTML
In addition, **remark-html** can be told how to compile nodes through
three `data` properties ([more information][to-hast]):
* `hName` — Tag name to compile as
* `hChildren` — HTML content to add (instead of `children` and `value`), in
[`hast`][hast]
* `hProperties` — Map of properties to add
For example, the following node:
```js
{
type: 'emphasis',
data: {
hName: 'i',
hProperties: {className: 'foo'},
hChildren: [{type: 'text', value: 'bar'}]
},
children: [{type: 'text', value: 'baz'}]
}
```
…would yield:
```markdown
<i class="foo">bar</i>
```
## Security
Use of `remark-html` is *unsafe* by default and opens you up to a
[cross-site scripting (XSS)][xss] attack.
Pass `sanitize: true` to prevent attacks.
Settings `sanitize` to anything else may be unsafe.
## Contribute

@@ -206,5 +223,5 @@

[build-badge]: https://img.shields.io/travis/remarkjs/remark-html/main.svg
[build-badge]: https://github.com/remarkjs/remark-html/workflows/main/badge.svg
[build]: https://travis-ci.org/remarkjs/remark-html
[build]: https://github.com/remarkjs/remark-html/actions

@@ -235,9 +252,11 @@ [coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-html.svg

[esmsh]: https://esm.sh
[health]: https://github.com/remarkjs/.github
[contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md
[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
[support]: https://github.com/remarkjs/.github/blob/HEAD/support.md
[support]: https://github.com/remarkjs/.github/blob/main/support.md
[coc]: https://github.com/remarkjs/.github/blob/HEAD/code-of-conduct.md
[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md

@@ -248,32 +267,28 @@ [license]: license

[unified]: https://github.com/unifiedjs/unified
[remark]: https://github.com/remarkjs/remark
[remark-plugins]: https://github.com/remarkjs/remark/blob/HEAD/doc/plugins.md#list-of-plugins
[github]: https://github.com/syntax-tree/hast-util-sanitize#schema
[remark2rehype]: https://github.com/remarkjs/remark-rehype
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[rehype]: https://github.com/rehypejs/rehype
[typescript]: https://www.typescriptlang.org
[rehype-stringify]: https://github.com/rehypejs/rehype/tree/HEAD/packages/rehype-stringify
[remark-rehype]: https://github.com/remarkjs/remark-rehype
[raw]: https://github.com/rehypejs/rehype-raw
[rehype-minify]: https://github.com/rehypejs/rehype-minify
[mdast]: https://github.com/syntax-tree/mdast
[rehype-format]: https://github.com/rehypejs/rehype-format
[mdast-node]: https://github.com/syntax-tree/mdast#nodes
[rehype-highlight]: https://github.com/rehypejs/rehype-highlight
[hast]: https://github.com/syntax-tree/hast
[rehype-meta]: https://github.com/rehypejs/rehype-meta
[to-html]: https://github.com/syntax-tree/hast-util-to-html
[rehype-stringify]: https://github.com/rehypejs/rehype/tree/main/packages/rehype-stringify
[to-hast-handlers]: https://github.com/syntax-tree/mdast-util-to-hast#optionshandlers
[sanitize]: https://github.com/syntax-tree/hast-util-sanitize
[github]: https://github.com/syntax-tree/hast-util-sanitize#schema
[hast-util-to-html]: https://github.com/syntax-tree/hast-util-to-html
[to-hast]: https://github.com/syntax-tree/mdast-util-to-hast#note
[integrations]: #integrations
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast
types/index.d.ts
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc