360 lines
12 KiB
Plaintext
360 lines
12 KiB
Plaintext
|
/**
|
|||
|
|
* Serialize hast as HTML.
|
|||
|
|
*
|
|||
|
|
* @param {Array<RootContent> | Nodes} tree
|
|||
|
|
* Tree to serialize.
|
|||
|
|
* @param {Options | null | undefined} [options]
|
|||
|
|
* Configuration (optional).
|
|||
|
|
* @returns {string}
|
|||
|
|
* Serialized HTML.
|
|||
|
|
*/
|
|||
|
|
export function toHtml(tree: Array<RootContent> | Nodes, options?: Options | null | undefined): string;
|
|||
|
|
/**
|
|||
|
|
* Serialize all children of `parent`.
|
|||
|
|
*
|
|||
|
|
* @this {State}
|
|||
|
|
* Info passed around about the current state.
|
|||
|
|
* @param {Parents | undefined} parent
|
|||
|
|
* Parent whose children to serialize.
|
|||
|
|
* @returns {string}
|
|||
|
|
*/
|
|||
|
|
export function all(this: State, parent: Parents | undefined): string;
|
|||
|
|
export type Nodes = import('hast').Nodes;
|
|||
|
|
export type Parents = import('hast').Parents;
|
|||
|
|
export type RootContent = import('hast').RootContent;
|
|||
|
|
export type Schema = import('property-information').Schema;
|
|||
|
|
export type StringifyEntitiesOptions = import('stringify-entities').Options;
|
|||
|
|
export type CharacterReferences = Omit<StringifyEntitiesOptions, 'attribute' | 'escapeOnly' | 'subset'>;
|
|||
|
|
/**
|
|||
|
|
* Configuration.
|
|||
|
|
*/
|
|||
|
|
export type Options = {
|
|||
|
|
/**
|
|||
|
|
* Do not encode some characters which cause XSS vulnerabilities in older
|
|||
|
|
* browsers (default: `false`).
|
|||
|
|
*
|
|||
|
|
* > ⚠️ **Danger**: only set this if you completely trust the content.
|
|||
|
|
*/
|
|||
|
|
allowDangerousCharacters?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Allow `raw` nodes and insert them as raw HTML (default: `false`).
|
|||
|
|
*
|
|||
|
|
* When `false`, `Raw` nodes are encoded.
|
|||
|
|
*
|
|||
|
|
* > ⚠️ **Danger**: only set this if you completely trust the content.
|
|||
|
|
*/
|
|||
|
|
allowDangerousHtml?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Do not encode characters which cause parse errors (even though they work),
|
|||
|
|
* to save bytes (default: `false`).
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
|
|||
|
|
* > errors are handled is well defined, so this works but isn’t pretty).
|
|||
|
|
*/
|
|||
|
|
allowParseErrors?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Use “bogus comments” instead of comments to save byes: `<?charlie>`
|
|||
|
|
* instead of `<!--charlie-->` (default: `false`).
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
|
|||
|
|
* > errors are handled is well defined, so this works but isn’t pretty).
|
|||
|
|
*/
|
|||
|
|
bogusComments?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Configure how to serialize character references (optional).
|
|||
|
|
*/
|
|||
|
|
characterReferences?: CharacterReferences | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Close SVG elements without any content with slash (`/`) on the opening tag
|
|||
|
|
* instead of an end tag: `<circle />` instead of `<circle></circle>`
|
|||
|
|
* (default: `false`).
|
|||
|
|
*
|
|||
|
|
* See `tightSelfClosing` to control whether a space is used before the
|
|||
|
|
* slash.
|
|||
|
|
*
|
|||
|
|
* Not used in the HTML space.
|
|||
|
|
*/
|
|||
|
|
closeEmptyElements?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Close self-closing nodes with an extra slash (`/`): `<img />` instead of
|
|||
|
|
* `<img>` (default: `false`).
|
|||
|
|
*
|
|||
|
|
* See `tightSelfClosing` to control whether a space is used before the
|
|||
|
|
* slash.
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*/
|
|||
|
|
closeSelfClosing?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Collapse empty attributes: get `class` instead of `class=""` (default:
|
|||
|
|
* `false`).
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: boolean attributes (such as `hidden`) are always collapsed.
|
|||
|
|
*/
|
|||
|
|
collapseEmptyAttributes?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Omit optional opening and closing tags (default: `false`).
|
|||
|
|
*
|
|||
|
|
* For example, in `<ol><li>one</li><li>two</li></ol>`, both `</li>` closing
|
|||
|
|
* tags can be omitted.
|
|||
|
|
* The first because it’s followed by another `li`, the last because it’s
|
|||
|
|
* followed by nothing.
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*/
|
|||
|
|
omitOptionalTags?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Leave attributes unquoted if that results in less bytes (default: `false`).
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*/
|
|||
|
|
preferUnquoted?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Preferred quote to use (default: `'"'`).
|
|||
|
|
*/
|
|||
|
|
quote?: Quote | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Use the other quote if that results in less bytes (default: `false`).
|
|||
|
|
*/
|
|||
|
|
quoteSmart?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* When an `<svg>` element is found in the HTML space, this package already
|
|||
|
|
* automatically switches to and from the SVG space when entering and exiting
|
|||
|
|
* it (default: `'html'`).
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: hast is not XML.
|
|||
|
|
* > It supports SVG as embedded in HTML.
|
|||
|
|
* > It does not support the features available in XML.
|
|||
|
|
* > Passing SVG might break but fragments of modern SVG should be fine.
|
|||
|
|
* > Use [`xast`][xast] if you need to support SVG as XML.
|
|||
|
|
*/
|
|||
|
|
space?: Space | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Join attributes together, without whitespace, if possible: get
|
|||
|
|
* `class="a b"title="c d"` instead of `class="a b" title="c d"` to save
|
|||
|
|
* bytes (default: `false`).
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
|
|||
|
|
* > errors are handled is well defined, so this works but isn’t pretty).
|
|||
|
|
*/
|
|||
|
|
tightAttributes?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Join known comma-separated attribute values with just a comma (`,`),
|
|||
|
|
* instead of padding them on the right as well (`,␠`, where `␠` represents a
|
|||
|
|
* space) (default: `false`).
|
|||
|
|
*/
|
|||
|
|
tightCommaSeparatedLists?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Drop unneeded spaces in doctypes: `<!doctypehtml>` instead of
|
|||
|
|
* `<!doctype html>` to save bytes (default: `false`).
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
|
|||
|
|
* > errors are handled is well defined, so this works but isn’t pretty).
|
|||
|
|
*/
|
|||
|
|
tightDoctype?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Do not use an extra space when closing self-closing elements: `<img/>`
|
|||
|
|
* instead of `<img />` (default: `false`).
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: only used if `closeSelfClosing: true` or
|
|||
|
|
* > `closeEmptyElements: true`.
|
|||
|
|
*/
|
|||
|
|
tightSelfClosing?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Use a `<!DOCTYPE…` instead of `<!doctype…` (default: `false`).
|
|||
|
|
*
|
|||
|
|
* Useless except for XHTML.
|
|||
|
|
*/
|
|||
|
|
upperDoctype?: boolean | null | undefined;
|
|||
|
|
/**
|
|||
|
|
* Tag names of elements to serialize without closing tag (default: `html-void-elements`).
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: It’s highly unlikely that you want to pass this, because
|
|||
|
|
* > hast is not for XML, and HTML will not add more void elements.
|
|||
|
|
*/
|
|||
|
|
voids?: ReadonlyArray<string> | null | undefined;
|
|||
|
|
};
|
|||
|
|
/**
|
|||
|
|
* HTML quotes for attribute values.
|
|||
|
|
*/
|
|||
|
|
export type Quote = '"' | "'";
|
|||
|
|
export type Settings = {
|
|||
|
|
/**
|
|||
|
|
* Do not encode some characters which cause XSS vulnerabilities in older
|
|||
|
|
* browsers (default: `false`).
|
|||
|
|
*
|
|||
|
|
* > ⚠️ **Danger**: only set this if you completely trust the content.
|
|||
|
|
*/
|
|||
|
|
allowDangerousCharacters: boolean;
|
|||
|
|
/**
|
|||
|
|
* Allow `raw` nodes and insert them as raw HTML (default: `false`).
|
|||
|
|
*
|
|||
|
|
* When `false`, `Raw` nodes are encoded.
|
|||
|
|
*
|
|||
|
|
* > ⚠️ **Danger**: only set this if you completely trust the content.
|
|||
|
|
*/
|
|||
|
|
allowDangerousHtml: boolean;
|
|||
|
|
/**
|
|||
|
|
* Do not encode characters which cause parse errors (even though they work),
|
|||
|
|
* to save bytes (default: `false`).
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
|
|||
|
|
* > errors are handled is well defined, so this works but isn’t pretty).
|
|||
|
|
*/
|
|||
|
|
allowParseErrors: boolean;
|
|||
|
|
/**
|
|||
|
|
* Use “bogus comments” instead of comments to save byes: `<?charlie>`
|
|||
|
|
* instead of `<!--charlie-->` (default: `false`).
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
|
|||
|
|
* > errors are handled is well defined, so this works but isn’t pretty).
|
|||
|
|
*/
|
|||
|
|
bogusComments: boolean;
|
|||
|
|
/**
|
|||
|
|
* Configure how to serialize character references (optional).
|
|||
|
|
*/
|
|||
|
|
characterReferences: CharacterReferences;
|
|||
|
|
/**
|
|||
|
|
* Close SVG elements without any content with slash (`/`) on the opening tag
|
|||
|
|
* instead of an end tag: `<circle />` instead of `<circle></circle>`
|
|||
|
|
* (default: `false`).
|
|||
|
|
*
|
|||
|
|
* See `tightSelfClosing` to control whether a space is used before the
|
|||
|
|
* slash.
|
|||
|
|
*
|
|||
|
|
* Not used in the HTML space.
|
|||
|
|
*/
|
|||
|
|
closeEmptyElements: boolean;
|
|||
|
|
/**
|
|||
|
|
* Close self-closing nodes with an extra slash (`/`): `<img />` instead of
|
|||
|
|
* `<img>` (default: `false`).
|
|||
|
|
*
|
|||
|
|
* See `tightSelfClosing` to control whether a space is used before the
|
|||
|
|
* slash.
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*/
|
|||
|
|
closeSelfClosing: boolean;
|
|||
|
|
/**
|
|||
|
|
* Collapse empty attributes: get `class` instead of `class=""` (default:
|
|||
|
|
* `false`).
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: boolean attributes (such as `hidden`) are always collapsed.
|
|||
|
|
*/
|
|||
|
|
collapseEmptyAttributes: boolean;
|
|||
|
|
/**
|
|||
|
|
* Omit optional opening and closing tags (default: `false`).
|
|||
|
|
*
|
|||
|
|
* For example, in `<ol><li>one</li><li>two</li></ol>`, both `</li>` closing
|
|||
|
|
* tags can be omitted.
|
|||
|
|
* The first because it’s followed by another `li`, the last because it’s
|
|||
|
|
* followed by nothing.
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*/
|
|||
|
|
omitOptionalTags: boolean;
|
|||
|
|
/**
|
|||
|
|
* Leave attributes unquoted if that results in less bytes (default: `false`).
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*/
|
|||
|
|
preferUnquoted: boolean;
|
|||
|
|
/**
|
|||
|
|
* Use the other quote if that results in less bytes (default: `false`).
|
|||
|
|
*/
|
|||
|
|
quoteSmart: boolean;
|
|||
|
|
/**
|
|||
|
|
* Join attributes together, without whitespace, if possible: get
|
|||
|
|
* `class="a b"title="c d"` instead of `class="a b" title="c d"` to save
|
|||
|
|
* bytes (default: `false`).
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
|
|||
|
|
* > errors are handled is well defined, so this works but isn’t pretty).
|
|||
|
|
*/
|
|||
|
|
tightAttributes: boolean;
|
|||
|
|
/**
|
|||
|
|
* Join known comma-separated attribute values with just a comma (`,`),
|
|||
|
|
* instead of padding them on the right as well (`,␠`, where `␠` represents a
|
|||
|
|
* space) (default: `false`).
|
|||
|
|
*/
|
|||
|
|
tightCommaSeparatedLists: boolean;
|
|||
|
|
/**
|
|||
|
|
* Drop unneeded spaces in doctypes: `<!doctypehtml>` instead of
|
|||
|
|
* `<!doctype html>` to save bytes (default: `false`).
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: intentionally creates parse errors in markup (how parse
|
|||
|
|
* > errors are handled is well defined, so this works but isn’t pretty).
|
|||
|
|
*/
|
|||
|
|
tightDoctype: boolean;
|
|||
|
|
/**
|
|||
|
|
* Do not use an extra space when closing self-closing elements: `<img/>`
|
|||
|
|
* instead of `<img />` (default: `false`).
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: only used if `closeSelfClosing: true` or
|
|||
|
|
* > `closeEmptyElements: true`.
|
|||
|
|
*/
|
|||
|
|
tightSelfClosing: boolean;
|
|||
|
|
/**
|
|||
|
|
* Use a `<!DOCTYPE…` instead of `<!doctype…` (default: `false`).
|
|||
|
|
*
|
|||
|
|
* Useless except for XHTML.
|
|||
|
|
*/
|
|||
|
|
upperDoctype: boolean;
|
|||
|
|
/**
|
|||
|
|
* Tag names of elements to serialize without closing tag (default: `html-void-elements`).
|
|||
|
|
*
|
|||
|
|
* Not used in the SVG space.
|
|||
|
|
*
|
|||
|
|
* > 👉 **Note**: It’s highly unlikely that you want to pass this, because
|
|||
|
|
* > hast is not for XML, and HTML will not add more void elements.
|
|||
|
|
*/
|
|||
|
|
voids: readonly string[];
|
|||
|
|
};
|
|||
|
|
/**
|
|||
|
|
* Namespace.
|
|||
|
|
*/
|
|||
|
|
export type Space = 'html' | 'svg';
|
|||
|
|
/**
|
|||
|
|
* Info passed around about the current state.
|
|||
|
|
*/
|
|||
|
|
export type State = {
|
|||
|
|
/**
|
|||
|
|
* Serialize one node.
|
|||
|
|
*/
|
|||
|
|
one: (node: Nodes, index: number | undefined, parent: Parents | undefined) => string;
|
|||
|
|
/**
|
|||
|
|
* Serialize the children of a parent node.
|
|||
|
|
*/
|
|||
|
|
all: (node: Parents | undefined) => string;
|
|||
|
|
/**
|
|||
|
|
* User configuration.
|
|||
|
|
*/
|
|||
|
|
settings: Settings;
|
|||
|
|
/**
|
|||
|
|
* Current schema.
|
|||
|
|
*/
|
|||
|
|
schema: Schema;
|
|||
|
|
/**
|
|||
|
|
* Preferred quote.
|
|||
|
|
*/
|
|||
|
|
quote: Quote;
|
|||
|
|
/**
|
|||
|
|
* Alternative quote.
|
|||
|
|
*/
|
|||
|
|
alternative: Quote;
|
|||
|
|
};
|