or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-hast-util-to-html

hast utility to serialize hast nodes to HTML strings with comprehensive formatting options

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/hast-util-to-html@9.0.x

To install, run

npx @tessl/cli install tessl/npm-hast-util-to-html@9.0.0

index.mddocs/

hast-util-to-html

hast-util-to-html is a utility that converts hast (Hypertext Abstract Syntax Tree) nodes into HTML strings. It provides comprehensive serialization options for controlling HTML output formatting, making it suitable for both pretty-printing and minification use cases.

Package Information

  • Package Name: hast-util-to-html
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install hast-util-to-html
    • For TypeScript: npm install hast-util-to-html @types/hast

Core Imports

import { toHtml } from "hast-util-to-html";

For CommonJS:

const { toHtml } = require("hast-util-to-html");

For TypeScript projects, you'll also need the hast type definitions:

import { toHtml } from "hast-util-to-html";
import type { Element, Root, Text } from "hast";

Basic Usage

import { h } from "hastscript";
import { toHtml } from "hast-util-to-html";

// Create hast tree
const tree = h(".alpha", [
  "bravo ",
  h("b", "charlie"),
  " delta ",
  h("a.echo", { download: true }, "foxtrot")
]);

// Convert to HTML
const html = toHtml(tree);
console.log(html);
// Output: <div class="alpha">bravo <b>charlie</b> delta <a class="echo" download>foxtrot</a></div>

Architecture

hast-util-to-html is part of the unified collective's syntax tree ecosystem. It works with hast (Hypertext Abstract Syntax Tree) nodes, which represent HTML structures in a standardized format. Typical workflow:

  1. Parse: HTML/Markdown → hast tree (using rehype-parse, mdast-util-to-hast)
  2. Transform: Modify the hast tree (using various hast utilities)
  3. Serialize: hast tree → HTML string (using hast-util-to-html)

The serialization process handles node types like element, text, comment, doctype, raw, and root, providing extensive control over the HTML output format.

Capabilities

HTML Serialization

Converts hast nodes or node arrays into HTML strings with extensive formatting control.

function toHtml(
  tree: Array<RootContent> | Nodes,
  options?: Options
): string;

Parameters:

  • tree: hast node or array of nodes to serialize
  • options: Configuration object for controlling HTML output (optional)

Returns: Serialized HTML string

Configuration Options

Comprehensive configuration interface for customizing HTML serialization behavior.

interface Options {
  allowDangerousCharacters?: boolean;
  allowDangerousHtml?: boolean;
  allowParseErrors?: boolean;
  bogusComments?: boolean;
  characterReferences?: CharacterReferences;
  closeEmptyElements?: boolean;
  closeSelfClosing?: boolean;
  collapseEmptyAttributes?: boolean;
  omitOptionalTags?: boolean;
  preferUnquoted?: boolean;
  quoteSmart?: boolean;
  quote?: Quote;
  space?: Space;
  tightAttributes?: boolean;
  tightCommaSeparatedLists?: boolean;
  tightDoctype?: boolean;
  tightSelfClosing?: boolean;
  upperDoctype?: boolean;
  voids?: ReadonlyArray<string>;
}

Key Options:

  • allowDangerousCharacters (boolean, default: false): Do not encode some characters which cause XSS vulnerabilities in older browsers
  • allowDangerousHtml (boolean, default: false): Allow raw nodes and insert them as raw HTML
  • allowParseErrors (boolean, default: false): Do not encode characters which cause parse errors to save bytes
  • bogusComments (boolean, default: false): Use "bogus comments" instead of comments to save bytes
  • characterReferences (CharacterReferences): Configure how to serialize character references
  • closeEmptyElements (boolean, default: false): Close SVG elements without content with slash on opening tag
  • closeSelfClosing (boolean, default: false): Close self-closing nodes with extra slash
  • collapseEmptyAttributes (boolean, default: false): Collapse empty attributes (get class instead of class="")
  • omitOptionalTags (boolean, default: false): Omit optional opening and closing tags
  • preferUnquoted (boolean, default: false): Leave attributes unquoted if that results in less bytes
  • quoteSmart (boolean, default: false): Use the other quote if that results in less bytes
  • quote (Quote, default: '"'): Preferred quote to use
  • space (Space, default: 'html'): Namespace (html or svg)
  • tightAttributes (boolean, default: false): Join attributes together without whitespace
  • tightCommaSeparatedLists (boolean, default: false): Join comma-separated attribute values with just a comma
  • tightDoctype (boolean, default: false): Drop unneeded spaces in doctypes
  • tightSelfClosing (boolean, default: false): Do not use extra space when closing self-closing elements
  • upperDoctype (boolean, default: false): Use <!DOCTYPE… instead of <!doctype…
  • voids (ReadonlyArray<string>): Tag names of elements to serialize without closing tag

Character References Configuration

Configuration for serializing character references in HTML output.

interface CharacterReferences {
  useNamedReferences?: boolean;
  omitOptionalSemicolons?: boolean;
  useShortestReferences?: boolean;
}

Fields:

  • useNamedReferences (boolean, default: false): Prefer named character references (&amp;) where possible
  • omitOptionalSemicolons (boolean, default: false): Whether to omit semicolons when possible
  • useShortestReferences (boolean, default: false): Prefer the shortest possible reference if that results in less bytes

Types

Quote Type

HTML quotes for attribute values.

type Quote = '"' | "'";

Space Type

Namespace specification for HTML or SVG serialization.

type Space = 'html' | 'svg';

Hast Node Types

Core hast node types that can be serialized to HTML.

type Nodes = Root | Element | Text | Comment | Doctype;

interface Root {
  type: 'root';
  children: RootContent[];
}

interface Element {
  type: 'element';
  tagName: string;
  properties?: Properties;
  children: (Element | Text | Comment)[];
}

interface Text {
  type: 'text';
  value: string;
}

interface Comment {
  type: 'comment';
  value: string;
}

interface Doctype {
  type: 'doctype';
  name: string;
  public?: string;
  system?: string;
}

type RootContent = Element | Text | Comment | Doctype;

interface Properties {
  [key: string]: boolean | null | number | string | (string | number)[];
}

Usage Examples

Integration with Hast Ecosystem

import { unified } from "unified";
import rehypeParse from "rehype-parse";
import { toHtml } from "hast-util-to-html";

// Parse HTML into hast tree
const processor = unified().use(rehypeParse, { fragment: true });
const tree = processor.parse('<p>Hello <strong>world</strong>!</p>');

// Serialize back to HTML with custom options
const html = toHtml(tree, {
  allowDangerousHtml: false,
  quote: '"',
  quoteSmart: true
});

console.log(html);
// Output: <p>Hello <strong>world</strong>!</p>

Pretty Printing

import { h } from "hastscript";
import { toHtml } from "hast-util-to-html";

const tree = h("article", [
  h("h1", "Title"),
  h("p", "Paragraph with ", h("strong", "bold"), " text.")
]);

const prettyHtml = toHtml(tree, {
  allowParseErrors: false,
  quote: '"',
  space: 'html'
});

console.log(prettyHtml);
// <article><h1>Title</h1><p>Paragraph with <strong>bold</strong> text.</p></article>

Minification

import { h } from "hastscript";
import { toHtml } from "hast-util-to-html";

const tree = h("div.container", [
  h("button", { type: "submit", disabled: true }, "Submit"),
  h("input", { type: "text", value: "" })
]);

const minifiedHtml = toHtml(tree, {
  allowParseErrors: true,
  bogusComments: true,
  collapseEmptyAttributes: true,
  omitOptionalTags: true,
  preferUnquoted: true,
  quoteSmart: true,
  tightAttributes: true,
  tightCommaSeparatedLists: true,
  tightDoctype: true,
  tightSelfClosing: true,
  closeSelfClosing: true
});

console.log(minifiedHtml);
// <div class=container><button type=submit disabled>Submit</button><input type=text value=""/></div>

SVG Serialization

import { s } from "hastscript/svg";
import { toHtml } from "hast-util-to-html";

const svgTree = s("svg", { viewBox: "0 0 100 100" }, [
  s("circle", { cx: "50", cy: "50", r: "40", fill: "red" })
]);

const svgHtml = toHtml(svgTree, {
  space: 'svg',
  closeEmptyElements: true,
  tightSelfClosing: false
});

console.log(svgHtml);
// <svg viewBox="0 0 100 100"><circle cx="50" cy="50" r="40" fill="red" /></svg>

Character Reference Handling

import { h } from "hastscript";
import { toHtml } from "hast-util-to-html";

const tree = h("p", "This contains <special> & \"quoted\" characters");

const htmlWithNamedRefs = toHtml(tree, {
  characterReferences: {
    useNamedReferences: true,
    omitOptionalSemicolons: false,
    useShortestReferences: false
  }
});

console.log(htmlWithNamedRefs);
// <p>This contains &lt;special&gt; &amp; &quot;quoted&quot; characters</p>