Ninjas Practicing Multidimensionality

    remark-html
    TypeScript icon, indicating that this package has built-in type declarations

    15.0.1 • Public • Published

    remark-html

    Build Coverage Downloads Size Sponsors Backers Chat

    remark plugin to add support for serializing HTML.

    Contents

    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 instead and finally use 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, format HTML, highlight code, add metadata, and a lot more.

    Install

    This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

    npm install remark-html

    In Deno with Skypack:

    import remarkHtml from 'https://cdn.skypack.dev/remark-html@15?dts'

    In browsers with Skypack:

    <script type="module">
      import remarkHtml from 'https://cdn.skypack.dev/remark-html@15?min'
    </script>

    Use

    Say we have the following file example.md:

    # Hello & World
    
    > A block quote.
    
    * Some _emphasis_, **importance**, and `code`.

    And our module example.js looks as follows:

    import {read} from 'to-vfile'
    import {unified} from 'unified'
    import remarkParse from 'remark-parse'
    import remarkHtml from 'remark-html'
    
    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.js yields:

    <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>

    API

    This package exports no identifiers. The default export is remarkHtml.

    unified().use(remarkHtml[, options])

    Add support for serializing HTML.

    options

    Configuration (optional). All options other than sanitize and handlers are passed to hast-util-to-html.

    options.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.

    options.sanitize

    How to sanitize the output (Object or boolean, default: true):

    • false — output is not sanitized, dangerous raw HTML persists
    • true — output is sanitized according to GitHub’s sanitation rules, dangerous raw HTML is dropped
    • Objectschema that defines how to sanitize output with hast-util-sanitize, dangerous raw HTML is dropped

    Types

    This package is fully typed with TypeScript. It exports an Options type, which specifies the interface of the accepted options.

    Compatibility

    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.

    This plugin works with unified version 6+ and remark version 7+.

    Security

    Use of remark-html is unsafe by default and opens you up to cross-site scripting (XSS) attacks. Pass sanitize: true to prevent attacks. Setting sanitize to anything else can be unsafe.

    Related

    Contribute

    See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

    This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

    License

    MIT © Titus Wormer

    Install

    npm i remark-html

    DownloadsWeekly Downloads

    139,502

    Version

    15.0.1

    License

    MIT

    Unpacked Size

    14.6 kB

    Total Files

    5

    Last publish

    Collaborators

    • johno
    • wooorm