CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-remark-html

remark plugin to compile Markdown to HTML

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

remark-html

remark-html is a unified (remark) plugin that compiles Markdown to HTML. It provides a shortcut for converting markdown documents into sanitized HTML output, serving as an alternative to using the full remark-rehype-rehype-stringify pipeline.

Package Information

  • Package Name: remark-html
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install remark-html

Core Imports

import remarkHtml from 'remark-html';

For CommonJS:

const remarkHtml = require('remark-html');

With TypeScript types:

import remarkHtml from 'remark-html';
import type { Options } from 'remark-html';

For advanced type usage:

import type { Schema } from 'hast-util-sanitize';
import type { Handlers } from 'mdast-util-to-hast';
import type { Root } from 'mdast';

Basic Usage

import remarkHtml from 'remark-html';
import remarkParse from 'remark-parse';
import { unified } from 'unified';

// Basic usage with default sanitization
const file = await unified()
  .use(remarkParse)
  .use(remarkHtml)
  .process('# Hello\n\n**World**');

console.log(String(file));
// Output: <h1>Hello</h1>\n<p><strong>World</strong></p>\n

Architecture

remark-html works within the unified ecosystem by:

  • Plugin Integration: Functions as a unified plugin that can be added to any remark processor
  • Markdown to HTML Pipeline: Converts mdast (markdown AST) directly to HTML without exposing intermediate hast (HTML AST)
  • Built-in Sanitization: Uses hast-util-sanitize by default to prevent XSS attacks
  • Compiler Pattern: Sets a compiler function on the unified processor to handle the final output transformation

Capabilities

HTML Compilation

Compiles markdown to HTML with built-in sanitization.

/**
 * Add support for serializing to HTML.
 * 
 * @param options - Configuration options (optional)
 * @returns Nothing (modifies processor)
 */
declare const remarkHtml: Plugin<
  [(Readonly<Options> | null | undefined)?],
  Root,
  string
>;

interface Options {
  /** How to turn mdast nodes into hast nodes */
  handlers?: Readonly<Handlers> | null | undefined;
  /** Sanitize the output, and how (default: true) */
  sanitize?: Readonly<Schema> | boolean | null | undefined;
  /** Control dangerous HTML elements */
  allowDangerousHtml?: boolean | null | undefined;
  /** Close self-closing elements */
  closeSelfClosing?: boolean | null | undefined;
  /** Omit optional closing tags */
  omitOptionalTags?: boolean | null | undefined;
  /** Character reference options */
  characterReferences?: {
    useShortestReferences?: boolean;
    omitOptionalSemicolons?: boolean;
  } | null | undefined;
  /** Additional options from hast-util-to-html */
  [key: string]: any;
}

Usage Examples:

// Default usage with sanitization
const processor = unified()
  .use(remarkParse)
  .use(remarkHtml);

// Disable sanitization (DANGEROUS - allows XSS)
const unsafeProcessor = unified()
  .use(remarkParse)
  .use(remarkHtml, { sanitize: false });

// Custom sanitization schema
const customProcessor = unified()
  .use(remarkParse)
  .use(remarkHtml, { 
    sanitize: { tagNames: ['p', 'strong', 'em', 'a'] }
  });

// Custom handlers for mdast to hast conversion
const handlerProcessor = unified()
  .use(remarkParse)
  .use(remarkHtml, {
    handlers: {
      paragraph(state, node) {
        // Custom paragraph handling
        return {
          type: 'element',
          tagName: 'div',
          properties: { className: ['custom-paragraph'] },
          children: state.all(node)
        };
      }
    }
  });

Configuration Options

Sanitization Control

Controls HTML sanitization to prevent XSS attacks.

/** Sanitization options */
sanitize?: Readonly<Schema> | boolean | null | undefined;
  • true (default): Uses safe default schema from hast-util-sanitize
  • false: DANGEROUS - Disables sanitization, allows arbitrary HTML
  • Schema: Custom sanitization schema object

Examples:

// Safe default (recommended)
.use(remarkHtml, { sanitize: true })

// Disable sanitization (dangerous)
.use(remarkHtml, { sanitize: false })

// Custom schema allowing only specific tags
.use(remarkHtml, { 
  sanitize: {
    tagNames: ['p', 'strong', 'em', 'a', 'ul', 'ol', 'li'],
    attributes: {
      a: ['href'],
      '*': ['className']
    }
  }
})

Custom Handlers

Customize how specific markdown nodes are converted to HTML.

/** Custom node handlers */
handlers?: Readonly<Handlers> | null | undefined;

Example:

.use(remarkHtml, {
  handlers: {
    // Custom link handler
    link(state, node) {
      return {
        type: 'element',
        tagName: 'a',
        properties: {
          href: node.url,
          target: '_blank',
          rel: 'noopener noreferrer'
        },
        children: state.all(node)
      };
    },
    
    // Custom code block handler
    code(state, node) {
      return {
        type: 'element',
        tagName: 'pre',
        properties: {
          className: node.lang ? [`language-${node.lang}`] : undefined
        },
        children: [{
          type: 'element',
          tagName: 'code',
          properties: {},
          children: [{ type: 'text', value: node.value }]
        }]
      };
    }
  }
})

HTML Output Options

Additional options from hast-util-to-html for controlling HTML output formatting. These are automatically available through the Options interface.

/** HTML output configuration options (subset of hast-util-to-html options) */
interface HtmlOutputOptions {
  /** Allow dangerous HTML in output */
  allowDangerousHtml?: boolean | null | undefined;
  /** Close self-closing tags */
  closeSelfClosing?: boolean | null | undefined;
  /** Omit optional closing tags */
  omitOptionalTags?: boolean | null | undefined;
  /** Character encoding options */
  characterReferences?: {
    useShortestReferences?: boolean;
    omitOptionalSemicolons?: boolean;
  } | null | undefined;
  /** Control quote usage in attributes */
  quoteSmart?: boolean | null | undefined;
  /** Collapse empty attributes */
  collapseEmptyAttributes?: boolean | null | undefined;
  /** Prefer unquoted attribute values */
  preferUnquoted?: boolean | null | undefined;
}

Examples:

// Control HTML output formatting
.use(remarkHtml, {
  closeSelfClosing: true,        // <br /> instead of <br>
  omitOptionalTags: false,       // Always include closing tags
  characterReferences: {
    useShortestReferences: true,  // Use shortest HTML entities
    omitOptionalSemicolons: false // Always include semicolons
  }
})

Types

/** Unified plugin type */
type Plugin<PluginParameters, Input, Output> = (
  ...parameters: PluginParameters
) => void;

/** Markdown AST root node */
interface Root {
  type: 'root';
  children: any[];
}

/** Node handlers for mdast to hast conversion */
interface Handlers {
  [nodeType: string]: (state: any, node: any) => any;
}

/** Sanitization schema from hast-util-sanitize */
interface Schema {
  tagNames?: string[];
  attributes?: Record<string, string[]>;
  protocols?: Record<string, string[]>;
  ancestors?: Record<string, string[]>;
  clobber?: string[];
  clobberPrefix?: string;
  strip?: string[];
  required?: Record<string, Record<string, any>>;
  allowComments?: boolean;
  allowDoctypes?: boolean;
}

Security Considerations

  • Default Safety: remark-html is safe by default with sanitize: true
  • XSS Prevention: Built-in sanitization prevents cross-site scripting attacks
  • Dangerous Mode: Setting sanitize: false is dangerous and should only be used with trusted input
  • Custom Schemas: When using custom sanitization schemas, ensure they don't allow dangerous tags or attributes
// SAFE (recommended)
.use(remarkHtml) // sanitize: true by default

// DANGEROUS - only use with trusted input
.use(remarkHtml, { sanitize: false })

// SAFE with custom restrictions
.use(remarkHtml, { 
  sanitize: { tagNames: ['p', 'strong', 'em'] }
})

Compatibility

  • Node.js: Version 16+
  • unified: Version 6+
  • remark: Version 15+
  • Module System: ESM only
  • TypeScript: Full type definitions included
  • Browsers: Compatible via ESM CDNs like esm.sh

Advanced Features

Data Fields for HTML Customization

mdast nodes can include data fields to customize HTML output:

interface NodeData {
  /** Override the HTML tag name */
  hName?: string;
  /** Set HTML attributes/properties */
  hProperties?: Record<string, any>;
  /** Replace node children with custom HTML */
  hChildren?: any[];
}

Examples:

// Override tag name
node.data = { hName: 'section' }; // <p> becomes <section>

// Add attributes
node.data = { 
  hProperties: { 
    className: ['highlight'], 
    id: 'special' 
  } 
};

// Replace content
node.data = { 
  hChildren: [
    { type: 'text', value: 'Custom content' }
  ] 
};

Error Handling

  • Unknown Nodes: Unknown mdast nodes are converted to <div> elements
  • File Extensions: Automatically sets output file extension to .html
  • Newline Handling: Adds trailing newline to non-empty output for consistency
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/remark-html@16.0.x
Publish Source
CLI
Badge
tessl/npm-remark-html badge