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 16.0.0

index.d.ts
lib/index.d.ts
lib/index.js

54

index.js

@@ -1,52 +0,2 @@

'use strict'
var toHast = require('mdast-util-to-hast')
var toHtml = require('hast-util-to-html')
var sanitize = require('hast-util-sanitize')
module.exports = plugin
function plugin(options) {
var settings = Object.assign({}, options || {})
let clean
if (typeof settings.sanitize === 'boolean') {
clean = settings.sanitize
settings.sanitize = undefined
}
if (typeof clean !== 'boolean') {
clean = true
}
this.Compiler = compiler
function compiler(node, file) {
var root = node && node.type && node.type === 'root'
var hast = toHast(node, {
allowDangerousHtml: !clean,
handlers: settings.handlers
})
var result
if (file.extname) {
file.extname = '.html'
}
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
}
}
// Note: types exposed from `index.d.ts`.
export {default} from './lib/index.js'

139

package.json
{
"name": "remark-html",
"version": "13.0.2",
"version": "16.0.0",
"description": "remark plugin to compile Markdown to HTML",
"license": "MIT",
"keywords": [
"unified",
"compile",
"html",
"markdown",
"mdast",
"plugin",
"remark",
"remark-plugin",
"plugin",
"mdast",
"markdown",
"html",
"stringify",
"compile"
"unified"
],

@@ -31,75 +31,88 @@ "repository": "remarkjs/remark-html",

],
"types": "types/index.d.ts",
"sideEffects": false,
"type": "module",
"exports": "./index.js",
"files": [
"types/index.d.ts",
"lib/",
"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": "^4.0.0",
"hast-util-sanitize": "^5.0.0",
"mdast-util-to-hast": "^13.0.0",
"unified": "^11.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",
"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",
"tape": "^5.0.0",
"tinyify": "^3.0.0",
"to-vfile": "^6.0.0",
"unified": "^9.0.0",
"xo": "^0.33.0"
"@types/hast": "^3.0.0",
"@types/node": "^20.0.0",
"c8": "^8.0.0",
"commonmark.json": "^0.30.0",
"hast-util-from-html": "^2.0.0",
"hast-util-to-html": "^9.0.0",
"prettier": "^3.0.0",
"remark-cli": "^11.0.0",
"remark-frontmatter": "^5.0.0",
"remark-gfm": "^4.0.0",
"remark-github": "^12.0.0",
"remark-parse": "^11.0.0",
"remark-preset-wooorm": "^9.0.0",
"remark-slug": "^7.0.0",
"remark-toc": "^9.0.0",
"type-coverage": "^2.0.0",
"typescript": "^5.0.0",
"vfile": "^6.0.0",
"xo": "^0.56.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": "tsc --build --clean && tsc --build && type-coverage",
"format": "remark . --frail --output --quiet && prettier . --log-level warn --write && xo --fix",
"prepack": "npm run build && npm run format",
"test": "npm run build && npm run format && npm run test-coverage",
"test-api": "node --conditions development test/index.js",
"test-coverage": "c8 --100 --reporter lcov npm run test-api"
},
"nyc": {
"check-coverage": true,
"lines": 100,
"functions": 100,
"branches": 100
},
"prettier": {
"tabWidth": 2,
"useTabs": false,
"bracketSpacing": false,
"singleQuote": true,
"bracketSpacing": false,
"semi": false,
"trailingComma": "none"
"tabWidth": 2,
"trailingComma": "none",
"useTabs": false
},
"remarkConfig": {
"plugins": [
"remark-preset-wooorm"
]
},
"typeCoverage": {
"atLeast": 100,
"detail": true,
"ignoreCatch": true,
"strict": true
},
"xo": {
"overrides": [
{
"files": [
"**/*.ts"
],
"rules": {
"@typescript-eslint/ban-types": "off"
}
},
{
"files": [
"test/**/*.js"
],
"rules": {
"no-await-in-loop": "off"
}
}
],
"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"
]
},
"remarkConfig": {
"plugins": [
"preset-wooorm"
]
"unicorn/prefer-at": "off"
}
}
}

305

readme.md

@@ -11,20 +11,60 @@ # 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)
* [`Options`](#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.
## 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(rehypeSanitize).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][esm].
In Node.js (version 16+), install with [npm][]:

@@ -35,41 +75,51 @@ ```sh

In Deno with [`esm.sh`][esmsh]:
```js
import remarkHtml from 'https://esm.sh/remark-html@16'
```
In browsers with [`esm.sh`][esmsh]:
```html
<script type="module">
import remarkHtml from 'https://esm.sh/remark-html@16?bundle'
</script>
```
## Use
Say we have the following file, `example.md`:
Say we have the following file `example.md`:
```markdown
# Hello & World
# Pluto
> A block quote.
* Some _emphasis_, **importance**, and `code`.
**Pluto** (minor-planet designation: **134340 Pluto**) is a
[dwarf planet](https://en.wikipedia.org/wiki/Dwarf_planet) in the
[Kuiper belt](https://en.wikipedia.org/wiki/Kuiper_belt).
```
And our script, `example.js`, looks as follows:
…and a module `example.js`:
```js
var fs = require('fs')
var unified = require('unified')
var markdown = require('remark-parse')
var html = require('remark-html')
import remarkHtml from 'remark-html'
import remarkParse from 'remark-parse'
import {read} from 'to-vfile'
import {unified} from 'unified'
unified()
.use(markdown)
.use(html)
.process(fs.readFileSync('example.md'), function (err, file) {
if (err) throw err
console.log(String(file))
})
const file = await unified()
.use(remarkParse)
.use(remarkHtml)
.process(await read('example.md'))
console.log(String(file))
```
Now, running `node example` yields:
…then running `node example.js` yields:
```html
<h1>Hello &#x26; World</h1>
<blockquote>
<p>A block quote.</p>
</blockquote>
<ul>
<li>Some <em>emphasis</em>, <strong>importance</strong>, and <code>code</code>.</li>
</ul>
<h1>Pluto</h1>
<p><strong>Pluto</strong> (minor-planet designation: <strong>134340 Pluto</strong>) is a
<a href="https://en.wikipedia.org/wiki/Dwarf_planet">dwarf planet</a> in the
<a href="https://en.wikipedia.org/wiki/Kuiper_belt">Kuiper belt</a>.</p>
```

@@ -79,110 +129,71 @@

### `remark().use(html[, options])`
This package exports no identifiers.
The default export is [`remarkHtml`][api-remark-html].
Serialize Markdown as HTML.
### `unified().use(remarkHtml[, options])`
##### `options`
Serialize markdown as HTML.
All options except for `sanitize` and `handlers` are passed to
[`hast-util-to-html`][to-html].
###### Parameters
###### `options.handlers`
* `options` ([`Options`][api-options], optional)
— configuration
Object mapping [mdast][] [nodes][mdast-node] to functions handling them.
This option is passed to [`mdast-util-to-hast`][to-hast-handlers].
###### Returns
###### `options.sanitize`
Transform ([`Transformer`][unified-transformer]).
How to sanitize the output (`Object` or `boolean`, default: `true`):
###### Notes
* `false`
— HTML is not sanitized, dangerous HTML persists
* `true`
— HTML is sanitized according to [GitHub’s sanitation rules][github],
dangerous HTML is dropped
* `Object`
— the object is treated as a `schema` for how to sanitize with
[`hast-util-sanitize`][sanitize], dangerous HTML is dropped
Passing `sanitize: false` is dangerous.
It allows arbitrary HTML and does not sanitize elements.
> 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].
### `Options`
For example, to add strict sanitation but allowing `className`s, use something
like:
Configuration (TypeScript type).
```js
// ...
var merge = require('deepmerge')
var github = require('hast-util-sanitize/lib/github')
###### Fields
var schema = merge(github, {attributes: {'*': ['className']}})
* `handlers` ([`Handlers` from
`mdast-util-to-hast`][mdast-util-to-hast-handlers], optional)
— how to turn mdast nodes into hast nodes
* `sanitize` ([`Schema` from
`hast-util-sanitize`][hast-util-sanitize-schema] or `boolean`, default:
`true`)
— sanitize the output, and how
* `...toHtmlOptions` ([`Options` from
`hast-util-to-html`][hast-util-to-html-options], optional)
— other options are passed to `hast-util-to-html`
remark()
.use(html, {sanitize: schema})
.processSync(/* … */)
```
## Types
## Integrations
This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].
`remark-html` works great with:
## Compatibility
* [`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]
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
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`.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `remark-html@^16`,
compatible with Node.js 16.
In addition, **remark-html** can be told how to compile nodes through
three `data` properties ([more information][to-hast]):
This plugin works with `unified` version 6+ and `remark` version 15+.
* `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
## Security
For example, the following node:
Use of `remark-html` is safe by default.
Passing `sanitize: false` is unsafe and opens you up to
[cross-site scripting (XSS)][wiki-xss] attacks.
A safe schema is used by default, but passing an unsafe schema is unsafe.
```js
{
type: 'emphasis',
data: {
hName: 'i',
hProperties: {className: 'foo'},
hChildren: [{type: 'text', value: 'bar'}]
},
children: [{type: 'text', value: 'baz'}]
}
```
## Related
…would yield:
* [`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
```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

@@ -204,5 +215,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

@@ -217,5 +228,5 @@ [coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-html.svg

[size-badge]: https://img.shields.io/bundlephobia/minzip/remark-html.svg
[size-badge]: https://img.shields.io/bundlejs/size/remark-html
[size]: https://bundlephobia.com/result?p=remark-html
[size]: https://bundlejs.com/?q=remark-html

@@ -234,9 +245,13 @@ [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[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

@@ -247,32 +262,32 @@ [license]: license

[remark]: https://github.com/remarkjs/remark
[hast-util-sanitize-schema]: https://github.com/syntax-tree/hast-util-sanitize#schema
[remark-plugins]: https://github.com/remarkjs/remark/blob/HEAD/doc/plugins.md#list-of-plugins
[hast-util-to-html-options]: https://github.com/syntax-tree/hast-util-to-html#options
[remark2rehype]: https://github.com/remarkjs/remark-rehype
[mdast-util-to-hast-handlers]: https://github.com/syntax-tree/mdast-util-to-hast#handlers
[rehype]: https://github.com/rehypejs/rehype
[rehype-format]: https://github.com/rehypejs/rehype-format
[rehype-stringify]: https://github.com/rehypejs/rehype/tree/HEAD/packages/rehype-stringify
[rehype-highlight]: https://github.com/rehypejs/rehype-highlight
[raw]: https://github.com/rehypejs/rehype-raw
[rehype-meta]: https://github.com/rehypejs/rehype-meta
[mdast]: https://github.com/syntax-tree/mdast
[rehype-minify]: https://github.com/rehypejs/rehype-minify
[mdast-node]: https://github.com/syntax-tree/mdast#nodes
[rehype-stringify]: https://github.com/rehypejs/rehype/tree/main/packages/rehype-stringify
[hast]: https://github.com/syntax-tree/hast
[remark]: https://github.com/remarkjs/remark
[to-html]: https://github.com/syntax-tree/hast-util-to-html
[remark-rehype]: https://github.com/remarkjs/remark-rehype
[to-hast-handlers]: https://github.com/syntax-tree/mdast-util-to-hast#optionshandlers
[typescript]: https://www.typescriptlang.org
[sanitize]: https://github.com/syntax-tree/hast-util-sanitize
[unified]: https://github.com/unifiedjs/unified
[github]: https://github.com/syntax-tree/hast-util-sanitize#schema
[unified-transformer]: https://github.com/unifiedjs/unified#transformer
[to-hast]: https://github.com/syntax-tree/mdast-util-to-hast#note
[wiki-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[integrations]: #integrations
[api-options]: #options
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[api-remark-html]: #unifieduseremarkhtml-options
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